6.1 Add LaTeX code to the preamble

The general structure of a LaTeX document is like this:

\documentclass{article}
% preamble
\begin{document}
% body
\end{document}

That is, you declare the document class in \documentclass{}, load certain LaTeX packages and set certain options if necessary in the preamble, and start writing the body of your document after \begin{document}. A Markdown document is mostly the body of the document.

If you want to add anything to the preamble, you have to use the includes option of pdf_document. This option has three sub-options: in_header, before_body, and after_body. Each of them takes one or multiple file paths. The file(s) specified in in_header will be added to the preamble. The files specified in before_body and after_body are added before and after the document body, respectively.

For example, below is a trick that turns hyperlinks in text into footnotes. This trick is useful when the PDF output document is printed on paper, because readers will not be able to click the links (generated from \href{URL}{text}) on paper but can see the URLs in footnotes. This trick displays both the text and URL.

% you may want to save a copy of \href before redefining it
% \let\oldhref\href
\renewcommand{\href}[2]{#2\footnote{\url{#1}}}

You can save the above code in a file with an arbitrary filename, e.g., preamble.tex. Then include it in the preamble through:

output:
  pdf_document:
    includes:
      in_header: "preamble.tex"

For this particular trick, you do not really have to implement it by yourself, but can simply set the YAML option links-as-notes to true because it is a built-in feature of Pandoc’s default LaTeX template (see Section 6.2).

Another way to add code to the preamble is to pass it directly to the header-includes field in the YAML frontmatter. We will show an example in Section 6.3. The advantage of using header-includes is that you can keep everything in one R Markdown document. However, if your report is to be generated in multiple output formats, we still recommend that you use the includes method, because the header-includes field is unconditional, and will be included in non-LaTeX output documents, too. By comparison, the includes option is only applied to the pdf_document format.