- The frontmatter to an R Markdown document.
You should consider no longer using LaTeX as a front-end for your manuscripts. Use a wrapper for LaTeX instead, like R Markdown.
I’ve discussed a previous move from LaTeX’ Beamer package to R Markdown, but was otherwise deferential to standard LaTeX for documents. However, LaTeX is ugly code. My manuscripts were also succumbing to “preamble creep”. My preambles kept getting bigger and messier with each successive manuscript. Standard LaTeX also can’t speak to R. A manuscript may require a careful and manual rewrite of the manuscript to better conform to the changes in the analysis.
I’ve started writing all my manuscripts now in R Markdown, which eliminates both markup (hence: “Markdown”) and allows me to better work with collaborators. In what follows, I discuss the properties of a template I wrote to render my PDFs and how LaTeX users could incorporate it into their own research workflow. I start with the YAML properties of my template and then discuss some basic Markdown syntax. I show what my Markdown academic manuscript template resembles in a full PDF thereafter. This PDF mirrors the post here but contains an extended discussion at the beginning of what R Markdown can do for issues of workflow. The PDF also contains examples how to execute R within the Markdown document. This type of “dynamic document” allows for the author to write the manuscript and reproduce the analysis in one fell swoop.
You can find the example .Rmd file, the example PDF, and my academic manuscript template on my Github at this repository.
Getting Started with YAML
The lion’s share of a R Markdown document will be raw text, though the front matter may be the most important part of the document. R Markdown uses YAML for its metadata and the fields differ from what an author would use for a Beamer presentation. I provide a sample YAML metadata largely taken from this exact document and explain it below.
will tell R Markdown we want a PDF document rendered with LaTeX. Since we are adding a fair bit of custom options to this call, we specify on the next line (with, importantly, a two-space indent). We specify additional output-level options underneath it, each are indented with four spaces. tells R Markdown to use to handle bibliographic citations.1 Thereafter, the next line () tells R Markdown to render a raw file along with the PDF document. This is useful for both debugging and the publication stage, when the editorial team will ask for the raw so that they could render it and later provide page proofs. The next line tells R Markdown to make sure that whatever images are included in the document are treated as figures in which our caption in brackets in a Markdown call is treated as the caption in the figure. The next line () tells R Markdown to use pdflatex and not some other option like . For my template, I’m pretty sure this is mandatory.2
The next line () tells R Markdown to use my custom LaTeX template.3 While I will own any errors in the code, I confess to “Frankensteining” this template from the default LaTeX template from Pandoc, Kieran Healy’s LaTeX template, and liberally using raw TeX from the Association for Computing Machinery’s (ACM) LaTeX template. I rather like that template since it resembles standard manuscripts when they are published in some of our more prominent journals. I will continue with a description of the YAML metadata in the next paragraph, though invite the curious reader to scroll to the end of the accompanying post to see the PDF this template produces.
The next fields get to the heart of the document itself. is, intuitively, the title of the manuscript. Do note that fields like do not have to be in quotation marks, but must be in quotation marks if the title of the document includes a colon. That said, the only reason to use a colon in an article title is if it is followed by a subtitle, hence the optional field (). Notice I “comment out” the subtitle in the above example with a pound sign since this particular document does not have a subtitle. If is included and has an accompanying entry, the ensuing title of the document gets an asterisk and a footnote. This field is typically used to advise readers that the document is a working paper or is forthcoming in a journal.
The next field () is a divergence from standard YAML, but I think it is useful. I will also confess to pilfering this idea from Kieran Healy’s template. Typically, multiple authors for a given document are separated by an in this field. However, standard LaTeX then creates a tabular field separating multiple authors that is somewhat restrictive and not easy to override. As a result, I use this setup (again, taken from Kieran Healy) to sidestep the restrictive rendering of authors in the standard tag. After , enter (no space before the dash) and fill in the field with the first author. On the next line, enter two spaces, followed by and the institute or university affiliation of the first author.
Do notice this can be repeated for however many co-authors there are to a manuscript. The rendered PDF will enter each co-author in a new line in a manner similar to journals like American Journal of Political Science, American Political Science Review, or Journal of Politics.
The next two fields pertain to the frontmatter of a manuscript. They should also be intuitive for the reader. should contain the abstract and should contain some keywords that describe the research project. Both fields are optional, though are practically mandatory. Every manuscript requires an abstract and some journals—especially those published by Sage—request them with submitted manuscripts. My template also includes these keywords in the PDF’s metadata.
comes standard with R Markdown and you can use it to enter the date of the most recent compile. I typically include the date of the last compile for a working paper in the field, so this field currently does not do anything in my Markdown-LaTeX manuscript template. I include it in my YAML as a legacy, basically.
The next items are optional and cosmetic. is a standard option in LaTeX. I set the margins at one inch, and you probably should too. is optional, but I use it to specify the Palatino font. The default option is Computer Modern Roman. sets, intuitively, the font size. The default is 10-point, but I prefer 11-point. is an optional field. If it is set as “double”, the ensuing document is double-spaced. “single” is the only other valid entry for this field, though not including the entry in the YAML metadata amounts to singlespacing the document by default. Notice I have this “commented out” in the example code.
The final two options pertain to the bibliography. specifies the location of the .bib file, so the author could make citations in the manuscript. specifies the type of bibliography to use. You’ll typically set this as APSR. You could also specify the relative path of my Journal of Peace Research .bst file if you are submitting to that journal.
Getting Started with Markdown Syntax
There are a lot of cheatsheets and reference guides for Markdown (e.g. Adam Prichard, Assemble, Rstudio, Rstudio again, Scott Boms, Daring Fireball, among, I’m sure, several others). I encourage the reader to look at those, though I will retread these references here with a minimal working example below.
That’s honestly it. Markdown takes the chore of markup from your manuscript (hence: “Markdown”).
On that note, you could easily pass most LaTeX code through Markdown if you’re writing a LaTeX document. However, you don’t need to do this (unless you’re using the math environment) and probably shouldn’t anyway if you intend to share your document in HTML as well.
The Template in Action
This is what the template looks like in action. You can also find how to use R Markdown and knitr to run R code within your R Markdown document, allowing for dynamic report generation.
Refer to my Github and my template repository for future updates.
Working title: You got Markdown in my LaTeX!
I hate writing documents in Microsoft Word and Apple Pages. I spend way too much time fiddling with formatting, page layout, and typesetting before everything looks the way I want it. And writing math equations, even with Word's GUI equation editor, is tedious and takes too much clicking. I'm a programmer—just let me use LaTeX's equation format instead!
If you want to write documents in Markdown, embed LaTeX, and generate PDFs, use Pandoc.
Skip down to Kung Fu Pandoc to get started!
So just use LaTeX, they said. It'll be fun, they said.
I like typesetting tools, and I like LaTeX... with reservations. Some of my complaints:
- The boilerplate needed to get a TeX document up and running is pretty massive.
- LaTeX is a pain in the ass to write. There is so much character overhead behind basic formatting.
- Holy reserved characters, Batman! Here are things you can't write in LaTeX without escaping:
It's not like I'd ever want to use a dollar sign in my budget report or an underscore in my C code.
- If you don't escape a character properly, you'll probably get a syntax error. LaTeX's syntax errors are cryptic and terrifying:
Wouldn't it be nice if...
This semester, I tried to write an assignment for class and found out my LaTeX build chain in Sublime broke. Instead of trying to troubleshoot it, I started thinking about what I'd like to use instead.
Here's why I love LaTeX:
- It lets me write equations quickly. Its equation syntax makes sense to me, and it's easy to import equations from Wikipedia pages.
- It's a typesetting program, not a WYSIWYG. No more screwing around with weird margin sliders and page layout tools and header settings: simply throw in your text, edit the settings once, and watch all your text reflow into place.
- It's easy to generate a PDF from a LaTeX file.
Here's why I prefer Markdown as a language to write formatted text:
- It's SUPER lightweight. , , .
- GitHub-flavored Markdown is super cool. It adds support for syntax-highlighted code blocks and tables! I like it so much I built a tool to generate Markdown tables from CSV files.
- You probably already know its syntax if you use GitHub or Reddit frequently.
I asked myself: "Self, wouldn't it be great if there were a typesetting tool that let you write documents in Markdown, embed LaTeX where you needed it, and generate PDFs?" And it turns out that already exists.
If you need to convert files from one markup format into another, pandoc is your swiss-army knife.
—John MacFarlane, author of pandoc
We'll use this Swiss Army knife called Pandoc to compile and export our Markdown-LaTeX docs. Let's try it out!
Install Pandoc and LaTeX
You'll need Pandoc and pdfTeX installed. If you can run and from a terminal, you're probably good to go.
If you're on a Mac, install Pandoc using Homebrew () and install MacTeX using their installer.
Get Your Source Doc
Here's a sample Markdown-plus-LaTeX document you can try to compile. Save that file somewhere as .
Compile Your Doc
Here's the command I used to compile —> :
See? It's that easy. Now open your PDF and you should see something like this:
Awesome. You're one step closer to well-documented world domination.
Automate That Ish with Sublime Text's Build Systems
Great! Now you can build Pandoc Markdown docs manually from the command line.
If you use Sublime Text like me, you might use the Build command ( or ) to build and run your scripts. When I used LaTeXTools, I got really used to checking how my LaTex looked when it was rendered by hitting . The LaTeX build command rendered my source document and opened a PDF viewer with the results.
I duplicated this in Sublime Text. Here's how you can too!
Create a new Sublime-Build file
Sublime-Build files tell Sublime Text how you want to build a document when you hit Ctrl-B.
Create a new Sublime-Build file by selecting
You'll get a document named that looks like this:
Write Your Pandoc Build Command
Replace the contents of your new document with the following:
Then change a few things:
If you're not on a Mac, remove the command.
is just for Macs—it opens the rendered file in Preview.app.
If you're not on a Mac, strip off the characters and everything after them. Your will look like this:
Remove the setting if you don't want it. Easier: just leave it in.
I found my Sublime install couldn't find unless I added this directory to the build system's path directly. You can probably leave it in—it shouldn't do any harm as long as Sublime can find .
Save Your New Build Command
The default save location will be . Save the file you just created into that directory as .
Set "Build System" to "Automatic"
Select to ensure Sublime picks your new Markdown build system.
Build a Markdown File!
Open the file you downloaded earlier in Sublime, then hit or . The Sublime Text console should open as it starts compiling your document, then print something like this when it's done:
Check the directory holding and look for a brand-new file!
You did it! I am very proud of you.
Bonus Round: Custom LaTeX Templates
You're a cool guy who knows cool stuff. Want to make your LaTeX docs even cooler? Add your own custom template.
Say I hate the default LaTeX monospace font and I want to add to fancy up my code blocks. Here's how I can do that:
- Save a LaTeX template somewhere on my computer
- Edit that template and add the LaTeX packages I want
- Ask Pandoc to use that template every time I compile my documents
Get a LaTeX template
I used this template provided by jgm. Seems to work great!
I saved mine as because I think that's where Pandoc templates usually go.
Edit that template
At line 134, I added some text to remind me where I can safely put commands, as well as my custom command:
Make Pandoc use that template
I edited my inside my file from the following:
I added a command-line argument pointing Pandoc to my default template as shown:
Now Pandoc uses my new template and makes my typewriter text not suck. Hooray!