3.3 PDF document
To create a PDF document from R Markdown, you specify thepdf_document output format in the YAML metadata:
---title:"Habits"author: John Doedate: March 22, 2005output: pdf_document---Within R Markdown documents that generate PDF output, you can use raw LaTeX, and even define LaTeX macros. See Pandoc’s documentation on theraw_tex extension for details.
Note that PDF output (including Beamer slides) requires an installation of LaTeX (see Chapter1).
3.3.1 Table of contents
You can add a table of contents using thetoc option and specify the depth of headers that it applies to using thetoc_depth option. For example:
---title:"Habits"output:pdf_document:toc:truetoc_depth:2---If the TOC depth is not explicitly specified, it defaults to 2 (meaning that all level 1 and 2 headers will be included in the TOC), while it defaults to 3 inhtml_document.
You can add section numbering to headers using thenumber_sections option:
---title:"Habits"output:pdf_document:toc:truenumber_sections:true---If you are familiar with LaTeX,number_sections: true means\section{}, andnumber_sections: false means\section*{} for sections in LaTeX (it also applies to other levels of “sections” such as\chapter{}, and\subsection{}).
3.3.2 Figure options
There are a number of options that affect the output of figures within PDF documents:
fig_widthandfig_heightcan be used to control the default figure width and height (6.5x4.5 is used by default).fig_cropcontrols whether thepdfcroputility, if available in your system, is automatically applied to PDF figures (this istrueby default).If you are usingTinyTeX as your LaTeX distribution, we recommend that you run
tinytex::tlmgr_install("pdfcrop")to install the LaTeX packagepdfcrop. You also have to make sure the system packageghostscriptis available in your system forpdfcropto work. For macOS users who have installed Homebrew,ghostscriptcan be installed viabrew install ghostscript.If your graphics device is
postscript, we recommend that you disable this feature (see more info in theknitr issue#1365).
fig_captioncontrols whether figures are rendered with captions (this istrueby default).devcontrols the graphics device used to render figures (defaults topdf).
For example:
---title:"Habits"output:pdf_document:fig_width:7fig_height:6fig_caption:true---3.3.3 Data frame printing
You can enhance the default display of data frames via thedf_print option. Valid values are presented in Table3.3.
| Option | Description |
|---|---|
| default | Call theprint.data.frame generic method |
| kable | Use theknitr::kable() function |
| tibble | Use thetibble::print.tbl_df() function |
| A custom function | Use the function to create the table. See3.1.6.2 |
For example:
---title:"Habits"output:pdf_document:df_print: kable---3.3.4 Syntax highlighting
Thehighlight option specifies the syntax highlighting style. Its usage inpdf_document is the same ashtml_document (Section3.1.4). For example:
---title:"Habits"output:pdf_document:highlight: tango---3.3.5 LaTeX options
Many aspects of the LaTeX template used to create PDF documents can be customized usingtop-level YAML metadata (note that these options do not appear underneath theoutput section, but rather appear at the top level along withtitle,author, and so on). For example:
---title:"Crop Analysis Q3 2013"output: pdf_documentfontsize: 11ptgeometry: margin=1in---A few available metadata variables are displayed in Table3.4 (consult the Pandoc manual forthe full list):
| Variable | Description |
|---|---|
| lang | Document language code |
| fontsize | Font size (e.g.,10pt,11pt, or12pt) |
| documentclass | LaTeX document class (e.g.,article) |
| classoption | Options for documentclass (e.g.,oneside) |
| geometry | Options for geometry class (e.g.,margin=1in) |
| mainfont, sansfont, monofont, mathfont | Document fonts (works only withxelatex andlualatex) |
| linkcolor, urlcolor, citecolor | Color for internal, external, and citation links |
3.3.6 LaTeX packages for citations
By default, citations are processed throughpandoc-citeproc, which works for all output formats. For PDF output, sometimes it is better to use LaTeX packages to process citations, such asnatbib orbiblatex. To use one of these packages, just set the optioncitation_package to benatbib orbiblatex, e.g.
---output:pdf_document:citation_package: natbib---3.3.7 Advanced customization
3.3.7.1 LaTeX engine
By default, PDF documents are rendered usingpdflatex. You can specify an alternate engine using thelatex_engine option. Available engines arepdflatex,xelatex, andlualatex. For example:
---title:"Habits"output:pdf_document:latex_engine: xelatex---The main reasons you may want to usexelatex orlualatex are: (1) They support Unicode better; (2) It is easier to make use of system fonts. See some posts on Stack Overflow for more detailed explanations, e.g.,https://tex.stackexchange.com/q/3393/9128 andhttps://tex.stackexchange.com/q/36/9128.
3.3.7.2 Keeping intermediate TeX
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 thekeep_tex option. For example:
---title:"Habits"output:pdf_document:keep_tex:true---3.3.7.3 Includes
You can do more advanced customization of PDF output by including additional LaTeX directives and/or content or by replacing the core Pandoc template entirely. To include content in the document header or before/after the document body, you use theincludes option as follows:
---title:"Habits"output:pdf_document:includes:in_header: preamble.texbefore_body: doc-prefix.texafter_body: doc-suffix.tex---3.3.7.4 Custom templates
You can also replace the underlying Pandoc template using thetemplate option:
---title:"Habits"output:pdf_document:template: quarterly-report.tex---Consult the documentation onPandoc templates for additional details on templates. You can also study thedefault LaTeX template as an example.
3.3.8 Other features
Similar to HTML documents, you can enable or disable certain Markdown extensions for generating PDF documents. See Section3.1.10.4 for details. You can also pass more custom Pandoc arguments through thepandoc_args option (Section3.1.10.5), and define shared options in_output.yml (Section3.1.11).