Chapter 3 Outputs

R Markdown can transform plain text and code into several different document formats. There are also multiple ways to Knit or render the output.

3.1 Output options

3.1.1 HTML

HTML is overall the most flexible. It supports the types of content we’re interested in creating as graduate students—tables, graphs, and the like—and you can easily transform your HTML output to a PDF with pagedown::chrome_print(file) if you have Google Chrome. The academic poster template that I like to use follows this process. You can also use this link to preview or share HTML outputs.

3.1.2 PDF

If you’re familiar with LaTeX, you may be inclined to output directly to a PDF, since you can include inline LaTeX code in your documents (more on this in Chapter 6). The CV and manuscript templates that I use rely on the fine-grained typesetting capabilities of LaTeX. To create a PDF, you need to have LaTeX installed locally. You should also install the tinytex distribution through the R console.

3.1.3 Word

You can also output to Microsoft Word and PowerPoint. I prefer not to use this option if I can help it, because you lose several important functions; for example, chunk options for aligning and setting the size of graphs and other images don’t work, and kable tables don’t appear correctly.

There are a few workarounds for these issues. Regarding images and graphs, I create them in a separate R script and save them in whatever size and format I need (e.g., .png). Then, I include them in my document using a code chunk.

Regarding tables, the best solution I’ve found is to create them in a separate R Markdown document that knits to HTML, then copy and paste them into the finished Word Document or PowerPoint. Obviously, this is not ideal, but this method retains the exact formatting of the tables from the HTML file. You can save tables as images as well, but the copy-paste solution works best for journals requiring editable tables.

3.2 Rendering options

3.2.1 Knit

You can specify a particular output type in the YAML header with output: output_format Then, you can press the Knit button or CTRL/command + shift + K to create or “knit” the document.

Be sure to pay attention to indentation and colon placement in your YAML header, especially as you start to specify options for particular output types. As a rule of thumb, if you have anything more than output: output_format, you need to indent every new line, and have a colon at the end of the previous line. See Section 4.3 for an example of this.

3.2.2 rmarkdown::render

Instead of knitting, you can also render files in the console with rmarkdown::render(file, output_format). This is essentially what Knit is doing. This approach allows you to create multiple output types quickly and easily. I usually customize my output very specifically for one output type by adding inline CSS or LaTeX code, so I really only use render when I’m making parameterized reports.

3.3 Rendering process

When you Knit or render your document, there’s a particular sequence of events that happens under the hood. Your R Markdown document is piped through to pandoc by the knitr package, which runs your code chunks and knits them together with the plain text you’ve included. Pandoc ultimately handles the conversion to a particular output format. Understanding this process can help you troubleshoot when you run into issues. You can find more on troubleshooting in Chapter 8.

Knitting process from Writing Your Thesis with R Markdown