Render to SVG/PDF. This method only works if diagrams are defined explicitly in files and not inlined into Markdown. To write this blog post and build the Cheatsheet I played around with non-realtime ways of rendering PlantUML diagrams into images. R Markdown documents are converted to PDF by first converting to a TeX file and then calling the LaTeX engine to convert to PDF. By default, this TeX file is removed, however if you want to keep it (e.g., for an article submission), you can specify the keeptex option. Ok in my case, I had a image in the same directory as the markdown file. The image was not referred to in the markdown document at all and had a name unrelated to the name of the markdown file. Just focus the window containing your markdown file and use the convert command (Packages Markdown to PDF Convert) or with the following shortcut ctrl-alt-e. The output PDF will be styled similar to the markdown on github.com. It will appear in the same directory as the Markdown you are converting, with the same name and a.pdf extension.

Introduction

If you have ever written a scientific paper in MS Word (or any other word processing software) then you’re probably experienced frustrations like me: Word constantly crashing when loaded with too many high-resolution figures, citations getting messed up when working with others that use different citation managers, or hard to keep track of hundreds of versions of the draft, etc.

Of course, Latex is always an excellent solution to all those problems. It separates content and formatting, allowing you to focus on content and leave the rest to those with expertise at it. A Tex file is also a pure text format so it’s easy to manage with a version control tool like git. However, Latex does have a rather steep learning curve. And a Tex file is not the most intuitive format to look at. For example, look at the below Tex format:

Another problem with writing in Latex is, while it’s not easy to learn Latex, it’s even harder to get all your collaborators on board, which is usually the case with scientific papers.

That led me to think: markdown is a fantastic format that is both intuitive and powerful. Why not write in markdown? After a short search, I’m happy to report that this is indeed possible!

What does writing a scientific paper require?

Content aside, to write a scientific paper efficiently, one needs at least the following elements:

1. Easy way to insert and manage citations.
2. Easy way to insert and manage high resolution figures
3. Easy way to format tables
4. Can be converted to other formats (pdf, html, etc)
5. Allows collaborative writing

Atom is an excellent text editor that with packages can do almost all of the above!

Required software and packages

• A Tex distribution for your OS (I used Tex Live for my linux system)

Once you have all required packages installed, it’s time to start writing!

Write a paper

Writing a paper in markdown is as easy as it sounds: use # for titles and subtitles, use | to format a table, among other things.

Write math equations

You can use Latex syntax to write a math equation, like so:

$f_A^2+2f_Af_B+f_B^2=1$

Import figures:

You can insert a figure in typical markdown way:

This would import the figure at current location. You can even further configure the figure like so:

Note: Because markdown preview enhanced by default uses a different render engine to render the preview, you will not see change to figure size in the preview but it will be rendered when converting to another output. You can also change its default markdown render engine to pandoc to see size change in preview.

Insert citations:

In order to insert a citation, you need to have zotero open. With zotero open, you can call up zotero citation picker by either pressing ctrl + alt + P or pressing ctrl + shift + P to call up the command palate and search for “zotero citations: pick”. In the citation picker window like below:

type in the reference you wish to insert and hit enter. A string of citation key should appear in your document:

Surround this reference key with [] and you’re good to go! Once you export this document to a pdf, word, or html format, the reference will be automatically appended to the end of your document and the ref key will be replaced with corresponding references, like so:

To add multiple citations, use ; to separate ref keys, like so:

Lastly, in order for pandoc to render citations correctly, you must provide a bib file that contains all your citations and their corresponding ref keys.

To do this, head on to zotero and click File -> Export library, in the format section, choose Better Bibtex. If you want the exported library up to date with your zotero library, check Keep updated. Once you have the exported library, add yaml frontmatter to the beginning of your document, like so:

Export to other formats

With pandoc, you can easily convert the markdown format to other text formats like pdf, word, and tex. To do this, first add output: word_document to your document’s frontmatter, like so:

and then you can right clock on the preview panel on the right to export the document through pandoc: This will output your document to a Word document. To output to PDF, simple change the value of output in frontmatter to pdf_document.

Conclusion

Markdown is an incredibly intuitive text format and yet still versatile and powerful enough for productive writing. It has recently surged to new favorite of many among developers, scientists, and journalists. It will certainly keep raising in popularity due to its friendliness and expandability.

Writing a scientific document in markdown has freed me of many frustrations caused by Word and with incredible pandoc, I never have to wrestle with any of my collaborators over which text editor we are to use. It has been a life saver!

byDanny QuahAug 2020

TL;DR: I write technical articles in LaTeX. But shorter, non-technical writings are easier to do in Markdown. How do I produce PDF from Markdown documents? Answer: provide YAML information in the Markdown; run Pandoc (typically through a Makefile or Atom's Markdown Preview Enhanced). To make all this work, some adjustment is needed in Pandoc options and template files.

Pandoc is a filter that takes a written document in its given format, and produces a version of that same document in yet a different format. I use Pandoc primarily to transform Markdown documents to PDF, but I also draw on Pandoc to convert Word or ODT documents to Markdown. Or vice versa.

Available official Pandoc documentation is voluminous. So as a matter of logic the knowledge to generate PDF from Markdown, to the user's desired degree of control, is already extant, out there somewhere. But a user just beginning might not find a good starting point, and without the ability to produce something useful quickly to show for their efforts, that user can lose the incentive to discover more, experiment, and improve. This writeup provides such a starting point for the beginner.

Pandoc Basics

To do its job, Pandoc has many options available from the command line. Using those can be as easy as just:

In this example, the input is the Open Document format file oldarchive.odt; output the Markdown document mydocument.md. Alternatively, I might have wanted the instruction:

where now input is the Markdown file oldarchive.md and output the Word document mydocument.docx.

The conversion will never be perfect, but in many cases the result provides a fine starting point for further fine-tuning.

Underlying Attributes

In the two examples just given, what you see when you render or display the input file, whether on-screen or on paper, is also approximately what you will see when you display the output file. In many Pandoc applications, that is all the user wants. The user, or their collaborators, will thereafter seek to make further changes only by editing the output file.

I myself prefer to edit Markdown directly but the people I work with insist on using Word. So I convert my Markdown file to docx, and thereafter that latter document is what we hand back and forth in our editing.

When the output is PDF, however, the result is no longer to be edited. Or, more accurately, to change the output file, users do not operate on the output file directly. Instead, a user will go back to the input file, make the alterations there, and then re-execute Pandoc to produce a new PDF. The PDF is just for show.

This workflow having the PDF endpoint will be familiar to TeX users. With Pandoc, however, it is not just TeX or its relatives that can provide input for beautifully structured PDFs. Markdown documents can provide that input as well. Since Markdown is lighter-weight than TeX, it will not of course do everything that the latter can. However, for many routine, not especially technical documents, Markdown provides a fine input engine as an alternative to TeX. The actual process is one where the Markdown document gets translated into LaTeX code, and then that result is fed into LaTeX itself.

(A purist who insists on writing everything in TeX might remember that LaTeX stands in relation to TeX much as I've described for Markdown, except that LaTeX is higher-up in the hierarchy and thus closer to TeX. But, again, for many routine, not especially technical writing, Markdown is already perfectly serviceable. Pandoc can be viewed as akin to lex and yacc for programmers. Who wants to code their own lexical analyzer in C from scratch every single time?)

Here, however, is both opportunity and potential pitfall. LaTeX and TeX are not translators that operate character by character or paragraph by paragraph. Instead, how they work is through structure. But how does structural information get conveyed from Markdown to LaTeX? Where in a Markdown document is encoded, in a single place, the information that, perhaps, every second-level heading is followed by a mediumskip? Or that all figures should float but be placed towards the top of the page closest to where they are first referenced?

This last feature might be observed to be empirically true in a specific document, but was that the intention of the author? Or did the figures just happen to come out that way? How can the author convey the information on what they intend here, in a way that Pandoc and thereafter LaTeX can use?

The answer is two-fold: first, through YAML information; second, through template files.

Markdown to PDF via LaTeX

For generating PDF, Pandoc will, behind the scenes, call on LaTeX or a related program. Pandoc can, to a great extent, do all this invisibly, but obviously those programs need to be installed somewhere on your system.

Any Markdown document can begin with YAML information, i.e., a section that starts and ends with three dashes in sequence on a line by themselves. In between those, individual lines contain key-value pairs that provide structural information on the document. Thus, a simple YAML header might be:

(preceded and ending with the three-dash sequence lines, of course). Like Python, YAML takes whitespace indentation to be significant. Comments are introduced by the # symbol, and are ignored by the processor.

As with the #-introduced comments, however, as far as Markdown rendering is concerned, the YAML key-value pairs too are ignored. Indeed, on most systems, all YAML information is ignored by Markdown. If you have a file containing just the above lines in, say, the file file.md, opening this file with a Markdown previewer typically shows the file contains nothing to display. Typora will open up file.md and display the YAML header but in non-editable form. Similarly, Github. (So, to edit YAML, you'll need to open the file with a text editor like Vim or Atom or similar.)

But if YAML is ignored, what is the point to it? Here is what's critical: YAML is used by Pandoc and by LaTeX when these two generate a PDF document from Markdown. YAML information is read off the Markdown document by Pandoc, gets passed by Pandoc to LaTeX, and with the latter employing YAML's key-value pairs as directives for structuring the document.

Thus, in many of my Markdown files destined for PDF output, the YAML header contains also:

(obviously somewhere between the beginning and ending 3-dash --- lines).

This is almost all it takes to generate a sensible-looking PDF from my Markdown document. The problem that remains is the author key-value pair. The maketitle command in LaTeX does not understand affiliation and email keys, only author. Thus, how above I have written the author information, to include affiliation and email explicitly, will fail on the standard Pandoc latex template. Instead, the YAML key-value pair needs to be

so that to add a second author, write:

This works for me.

It can be neater, however, to separate out affiliation and email information explicitly, as in the YAML above. To use that then, the latex template that Pandoc uses will need to be modified.

First, generate the default latex template that will subsequently be changed:

I put mytemplate.tex in ~/.pandoc/templates/ as that latter is the default personal folder that will be recognised subsequently by the Pandoc option

Now open up mytemplate.tex in a text editor and change the statement (or recognisable statement block) from:

to

As you can see, the replacement code contains reference to affiliation and email, as in the YAML header, but which is not generally available in LaTeX. What makes this work is that the replacement code also loads in the package authbok (in its second line), that will then properly situate the affiliation and email key-values when the LaTeX maketitle instruction is invoked.

If you decide to use the more elaborate, compacted YAML header and not change the latex template, then

produces the desired myinput.pdf. If, however, you decide to use the more explicit and structured affiliation and email YAML header and the modified mytemplate.tex then use

instead, i.e., add the explicit new --template to your Pandoc call.

If you want to inspect the LaTeX code that's produced along the way, you can undertake this production in two steps:

adding in --template=mytemplate.tex as needed in the pandoc call.

Atom Markdown Pdf エラー

References