5.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 the URLs in hyperlinks into footnotes. This trick is useful because (by default) readers do not know the actual URL when they see the text in PDF generated from \href{URL}{text}. 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"

Another way to add code to the preamble is to use the header-includes field in the YAML frontmatter. We will show an example in Section 5.2. 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 into 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.