Motivation
I once spent a few days trying to tame tables in a Bookdown pdf_book format. I checked a few R packages that were supposed to help me, but they weren't visual, took time to learn, and were eventually not very useful. For instance, when I tried to add a caption to my table, the subsequent text that should have followed the table ended up inside it instead. Now I know that it wasn’t the fault of the package authors, but rather the way the package output was rendered in the R Markdown PDF output—an issue that might be fixed by the time you are reading this post. I looked up the Bookdown book by Yihui Xie and noticed he favors the HTML format, or at least methods that work with both CSS and LaTeX. However, his preferred method didn't even fit into the visible part of my RStudio editor window.
I ultimately decided to focus on the PDF format because I wanted a book with easy references and an index. Plus, I can host it on my GitHub account, update versions seamlessly, and download it to read offline.
While searching the internet, I discovered a lot of advice recommending a switch to HTML/CSS format as well. Apparently, I had no choice but to roll up my sleeves and get my hands dirty. During this process, I learned that my R Markdown file is converted to a .tex format before being turned into a PDF. This made me think: why not just write the exact LaTeX chunk I want, rather than relying on the correctness of the R Markdown rendering?
I already had an unsuccessful experience a few years back when I tried using a LaTeX package in R Markdown and it didn't work. However, I decided to try again, hoping that R Markdown had matured since then. I examined different methods used in the Bookdown pdf_book format and discovered a lot of raw LaTeX commands and environments being used as-is. I tried the basic LaTeX environment for a table—tabular—and it worked! Though, for a really professional-looking table, you still need the LaTeX booktabs package.
LaTeX intro
If you do not know LaTeX at all, here are a few introductory tips. Please remember that these tips apply specifically to the pdf_book format; if you try to use them for text intended for HTML format as well, they will not cooperate.
1. LaTeX commands start with a backslash (\). The backslash itself is not printed in the final document; it simply denotes the beginning of a command. For example, the following command places everything that follows it onto a brand-new page:
\newpage
Here are a couple of other commands used to add vertical space, which is helpful if you want more distance between your sections, pictures, or tables:
\vspace{5mm}
\vspace{1cm}
Note the use of the metric system here. Both of these commands should be padded by empty lines before and after to work properly.
2. Whitespace is collapsed. Just like in Markdown, any number of consecutive empty lines in LaTeX is collapsed into a single line break, and multiple consecutive inline spaces are collapsed into a single space.
3. LaTeX uses "environments." Environments are used for specific chunks of content, such as pictures, tables, formulas, font types, and sizes. Their start and end points must be explicitly marked and properly nested. Do not forget to close an environment or confuse which environment ends where! The LaTeX gods will be furious and refuse to compile your document until you fix your mistakes. Worse yet, you are unlikely to get a helpful error message, as the compiler assumes you must know what you did wrong. 💣
4. Basic and many other LaTeX environments use the same command to go to the next line: a double backslash:
\\
One notable exception are math environments, which are a whole new game. A basic, simple format is when you only use single dollar signs; for example, $x^2$ will be converted to x-squared in math script on the PDF page:
But when you need to display a bunch of formulas together, LaTeX has a choice of environments for you. By the way, to avoid LaTeX assuming that you mean to open a math environment when you use $, use a backslash before it. Otherwise, you will see a processing error. For example, if you want to get $5.67 on your Markdown page, do it this way:\$5.67.
Back to tables!
The LaTeX environment we need here starts with \begin{tabular} and ends with \end{tabular}. Below is an example that includes all the necessary elements of a basic LaTeX tabular environment, followed by how it is rendered and an explanation.
\begin{tabular}{l l}
column 1, row 1 & column 2, row 1 \\
column 1, row 2 & column 2, row 2 \\
\end{tabular}
Here is what you see on your PDF page:
Note how we correctly stated the start and termination of the environment. In addition, there are a few elements that are mandatory:
1. As you see, I have {l l} right after the environment opening. This is for column alignment selections. I have two of them because I have two columns, and the "l" option means that each column must be left-aligned. Other options here are "r" for right-aligned and "c" for centered; they do not depend on each other.
2. Each table row ends with a double backslash: \\.
3. Within a row, entries for different columns are separated by the & symbol.
This table is rather bare-bones, and we do not have divider lines or borders.
Now, let us add horizontal and vertical borders. For the horizontal lines, we will use the commands \toprule, \bottomrule, and \midrule. The first two can appear only once each in the table, while the last one can be used as many times as needed. Here is what it looks like as raw text:
\begin{tabular}{l l}
\toprule
column 1, row 1 & column 2, row 1 \\
\midrule
column 1, row 2 & column 2, row 2 \\
\bottomrule
\end{tabular}
Here is what you will see when you process the commands:
Now, we need to add vertical borders. They are less easy to spot in the code because they are added directly to the alignment options; so instead of
{l l}, we type
{|l|l|}:
\begin{tabular}{|l|l|}
\toprule
column 1, row 1 & column 2, row 1 \\
\midrule
column 1, row 2 & column 2, row 2 \\
\bottomrule
\end{tabular}
You are not obligated to write out your rows and columns exactly as you would like to see them rendered, but it certainly helps. Technically, you could type all of them on a single line or break the line at any space. I have seen people place horizontal line commands at the end of typed
.tex rows; your LaTeX compiler does not care. Your coauthors may have specific preferences, though.
This LaTeX code can be used as-is in R Markdown if you have the PDF option specified for your output in the YAML metadata (header). Hope it helps!