R Markdown on Github Pages | Set LaTeX Parameters in bookdown
Specify LaTeX Parameters in R Markdown
How to set LaTeX parameters in R Markdown. From simple to complex document structures — an example with bookdown.
I started my Bayesian Network Compendium as a classical LaTeX document. It’s purpose is not only to focus on theory but also show practical examples which I demonstrate in the programming language R. This brought me to switch from a vanilla LaTeX document to R Markdown.
Let me start with a very brief comparison of the markup languages LaTeX, Markdown and R Markdown to help you better understand how they play in concert. Then I will guide you on the implementation of user specific LaTeX settings in R Markdown documents.
At the end you will:
- have an overview over the landscape of some popular markup languages.
- understand how R Markdown teams up with LaTeX to render math expressions.
- be able to implement your own LaTeX settings in R Markdown and specifically in the R Package bookdown.
I wrote this article with the intention to share my knowledge which might save other people’s time and nerves. I’m by far not an expert and I would love to hear if this article was helpful for you!
LaTeX vs. Markdown vs. R Markdown
It is not difficult to fill books about LaTeX. But I try to keep it to one sentence for now: LaTeX is well known for its tidy typesetting (i.a. of mathematical formulas) by taking advantage of the TeX typesetting system and is very popular especially in the academic world.
Markdown is a lightweight markup language which is already easy to read in its raw form and can be converted to for example .html documents. Today there exist many different flavours and syntaxes. For example, Whatsapp released its own Markup syntax in 2016 to provide basic formatting options to messages.
R Markdown is a file format combining executable R code chunks with the easy syntax of a Markdown document. This combination allows us to easily present our analyses reproducibly in beautiful and interactive documents. R Markdown is based on the minimalistic assumption that it is sufficient to have only a limited number of Markdown elements available to create great documents.
“Wealth consists not in having great possessions, but in having few wants.”
― Epictetus
Among those features that are available in R Markdown there is the possibility to format math equations with LaTeX.
As an example I will use the problem that I faced while working on the Bayesian Network Compendium as bookdown project: To display the symbol for conditional independence was quite easy in LaTeX.
\perp\!\!\!\perp 
To reduce typos and increase code readability I defined a new LaTeX command.
Define a new command in LaTeX
I was looking for a way to abbreviate this complex syntax in a short way. The conditional independence symbol can be defined in LaTeX in multiple ways. Just for completeness, beside \newcommand there are different ways on how to define a new command in LaTeX (for example using the raw TeX command \def). I decided on this one:
\newcommand{\ci}{\perp\!\!\!\perp}LaTeX \newcommand in R Markdown
Defining a new LaTeX command in a R Markdown document is also quite straight forward.
- Define the command as you would in LaTeX.
- Put it below the YAML header at the beginning of your R Markdown file.
- Call the new command within $…$ to let R Markdown know that this command is defined in the LaTeX environment.
---
title: Title
author: Author
date: "10/10/2020"
output: html_document
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
\newcommand{\ci}{\perp\!\!\!\perp}
## R Markdown
This is an R Markdown document. Inline math equations are put in between single dollar signs $(A \ci B)$. Math equation blocks are framed with double dollar signs$$\begin{equation}
(X \ci Y) | Z \iff Pr(A \cap B |C) = Pr(A|C)Pr(B|C)
\end{equation}$$
More details about LaTeX macros in R Markdown can be found in the Pandoc Markdown manual.
Alternatively you can use a separate file with your LaTeX specific definitions. This is particularly helpful if you require specific LaTeX packages within the math environment of R Markdown or you encounter issues because you use a special output format.
- Create a new file called
preamble.tex - Add the
\usepackageand\newcommandcalls from the preamble part of your LaTeX document to this file. This could then look like this:
\usepackage{booktabs}
\usepackage{amsthm}
\newcommand{\ci}{\perp\!\!\!\perp}- Link the file
preamble.texwith your R Markdown. Tell the LaTeX engine of R Markdown to run this file before the main body. You can do that in the YAML header of the R Markdown file:
---
title: Title
author: Author
date: "10/10/2020"
output:
html_document:
includes:
in_header: preamble.tex
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```## R Markdown
This is an R Markdown document. Inline math equations are put in between single dollar signs $(A \ci B)$. Math equation blocks are framed with double dollar signs$$\begin{equation}
(X \ci Y) | Z \iff Pr(A \cap B |C) = Pr(A|C)Pr(B|C)
\end{equation}$$
Pretty neat, isn’t it? Well, there’s one drawback though. The LaTeX syntax provided through preamble.tex is not portable to other output formats. In other words, if you render your bookdown to .html or ePUBS, your packages are not loaded and no new command is defined. Why this is and how to handle other output formats is explained in the next section.
LaTeX \newcommand in bookdown
The R package bookdown can render the output in different formats such as .html, .pdf or ePUBS. Output format specific options are provided in the _output.yml file in the root project directory.
With bookdown::gitbook you’ll end with a separate .html file for each segment¹ specified with split_by: . For example with split_by: chapter+number you’ll get for each chapter a separate .html file whereas with split_by: section+number you end with separate .html files for each section. For .html output, bookdown renders LaTeX math equations with the MathJax library. MathJax is not able to detect the LaTeX macros specified in the preamble.tex for each .html file. The solution here is to create a file named mathjax_header.html in the root of the project directory with the content from preamble.tex (don’t delete it! We need it later again). Remember to reformat it to a html snippet. For my example above mathjax_header.html would look like this:
<span class="math inline">
\(\newcommand{\ci}{\perp\!\!\!\perp}\)
</span>We now need to tell bookdown to use mathjax_header.html when it renders to .html. This is done in bookdown’s _output.yml
bookdown::gitbook:
css: style.css
split_by: chapter+number
includes:
in_header: mathjax_header.htmlIn the bookdown::pdf_book section of the _output.yml file you specify the settings for rendering to pdf. That’s where preamble.tex comes back in the game:
bookdown::pdf_book:
includes:
in_header: preamble.texConclusion
You learned how to implement your own LaTeX command in a classic R Markdown document and also in the more complex bookdown framework.
Additionally I explained you the basic concept of how R Markdown and bookdown compile LaTeX math expressions.
If you’re looking for more detailed information, check out the links in the text.
Read more about my bookdown project in this previous article:
¹ Cave: In bookdown::gitbook the argument split_by is different to bookdown::tufte_html_book
bookdown::gitbook:
split_by: chapter+number
bookdown::tufte_html_book:
split_by: section+number
