R Markdown Formatting
The R Markdown cheat sheet is still the best place to learn about most the basic syntax you can use. If you are looking for potential extensions to the formatting, the bookdown package is also worth exploring. The first official book authored by the core R Markdown developers that provides a comprehensive and accurate reference to the R Markdown ecosystem. With R Markdown, you can easily create.
2.5 Markdown syntax
The text in an R Markdown document is written with the Markdown syntax. Precisely speaking, it is Pandoc’s Markdown. There are many flavors of Markdown invented by different people, and Pandoc’s flavor is the most comprehensive one to our knowledge. You can find the full documentation of Pandoc’s Markdown at https://pandoc.org/MANUAL.html. We strongly recommend that you read this page at least once to know all the possibilities with Pandoc’s Markdown, even if you will not use all of them. This section is adapted from Section 2.1 of Xie (2016), and only covers a small subset of Pandoc’s Markdown syntax.
2.5.1 Inline formatting
R Markdown Cheat Sheet
Inline text will be italic if surrounded by underscores or asterisks, e.g., _text_ or *text*. Bold text is produced using a pair of double asterisks (**text**). A pair of tildes (~) turn text to a subscript (e.g., H~3~PO~4~ renders H3PO4). A pair of carets (^) produce a superscript (e.g., Cu^2+^ renders Cu2+).
To mark text as inline code, use a pair of backticks, e.g., `code`. To include (n) literal backticks, use at least (n+1) backticks outside, e.g., you can use four backticks to preserve three backtick inside: ```` ```code``` ````, which is rendered as ```code```.
Hyperlinks are created using the syntax [text](link), e.g., [RStudio](https://www.rstudio.com). The syntax for images is similar: just add an exclamation mark, e.g., . Footnotes are put inside the square brackets after a caret ^[], e.g., ^[This is a footnote.].
There are multiple ways to insert citations, and we recommend that you use BibTeX databases, because they work better when the output format is LaTeX/PDF. Section 2.8 of Xie (2016) has explained the details. The key idea is that when you have a BibTeX database (a plain-text file with the conventional filename extension .bib) that contains entries like:
You may add a field named bibliography to the YAML metadata, and set its value to the path of the BibTeX file. Then in Markdown, you may use @R-base (which generates “R Core Team (2021)”) or [@R-base] (which generates “(R Core Team 2021)”) to reference the BibTeX entry. Pandoc will automatically generated a list of references in the end of the document.
2.5.2 Block-level elements
Section headers can be written after a number of pound signs, e.g.,
If you do not want a certain heading to be numbered, you can add {-} or {.unnumbered} after the heading, e.g.,
Unordered list items start with *, -, or +, and you can nest one list within another list by indenting the sub-list, e.g.,
The output is:
- one item
- one item
- one item
- one more item
- one more item
- one more item
Ordered list items start with numbers (you can also nest lists within lists), e.g.,
The output does not look too much different with the Markdown source:
- the first item
- the second item
- the third item
- one unordered item
- one unordered item
Blockquotes are written after >, e.g.,
The actual output (we customized the style for blockquotes in this book):
R Markdown Format Title
“I thoroughly disapprove of duels. If a man should challenge me,I would take him kindly and forgivingly by the hand and lead himto a quiet place and kill him.”
— Mark Twain
Plain code blocks can be written after three or more backticks, and you can also indent the blocks by four spaces, e.g.,
In general, you’d better leave at least one empty line between adjacent but different elements, e.g., a header and a paragraph. This is to avoid ambiguity to the Markdown renderer. For example, does “#” indicate a header below?
And does “-” mean a bullet point below?
Different flavors of Markdown may produce different results if there are no blank lines.
2.5.3 Math expressions
Inline LaTeX equations can be written in a pair of dollar signs using the LaTeX syntax, e.g., $f(k) = {n choose k} p^{k} (1-p)^{n-k}$ (actual output: (f(k)={n choose k}p^{k}(1-p)^{n-k})); math expressions of the display style can be written in a pair of double dollar signs, e.g., $$f(k) = {n choose k} p^{k} (1-p)^{n-k}$$, and the output looks like this:
[fleft(kright)=binom{n}{k}p^kleft(1-pright)^{n-k}]
You can also use math environments inside $ $ or $$ $$, e.g.,
[begin{array}{ccc}x_{11} & x_{12} & x_{13}x_{21} & x_{22} & x_{23}end{array}]
[X = begin{bmatrix}1 & x_{1}1 & x_{2}1 & x_{3}end{bmatrix}]
[Theta = begin{pmatrix}alpha & betagamma & deltaend{pmatrix}]
[begin{vmatrix}a & bc & dend{vmatrix}=ad-bc]
Note: This book has been published by Chapman & Hall/CRC. The online version of this book is free to read here (thanks to Chapman & Hall/CRC), and licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
The document format “R Markdown” was first introduced in the knitr package (Xie 2015, 2021b) in early 2012. The idea was to embed code chunks (of R or other languages) in Markdown documents. In fact, knitr supported several authoring languages from the beginning in addition to Markdown, including LaTeX, HTML, AsciiDoc, reStructuredText, and Textile. Looking back over the five years, it seems to be fair to say that Markdown has become the most popular document format, which is what we expected. The simplicity of Markdown clearly stands out among these document formats.
However, the original version of Markdown invented by John Gruber was often found overly simple and not suitable to write highly technical documents. For example, there was no syntax for tables, footnotes, math expressions, or citations. Fortunately, John MacFarlane created a wonderful package named Pandoc (http://pandoc.org) to convert Markdown documents (and many other types of documents) to a large variety of output formats. More importantly, the Markdown syntax was significantly enriched. Now we can write more types of elements with Markdown while still enjoying its simplicity.
Markdown Cheatsheet Pdf
In a nutshell, R Markdown stands on the shoulders of knitr and Pandoc. The former executes the computer code embedded in Markdown, and converts R Markdown to Markdown. The latter renders Markdown to the output format you want (such as PDF, HTML, Word, and so on).
The rmarkdown package (Allaire, Xie, McPherson, et al. 2021) was first created in early 2014. During the past four years, it has steadily evolved into a relatively complete ecosystem for authoring documents, so it is a good time for us to provide a definitive guide to this ecosystem now. At this point, there are a large number of tasks that you could do with R Markdown:
Compile a single R Markdown document to a report in different formats, such as PDF, HTML, or Word.
Create notebooks in which you can directly run code chunks interactively.
Make slides for presentations (HTML5, LaTeX Beamer, or PowerPoint).
Produce dashboards with flexible, interactive, and attractive layouts.
Build interactive applications based on Shiny.
Write journal articles.
Author books of multiple chapters.
Generate websites and blogs.
There is a fundamental assumption underneath R Markdown that users should be aware of: we assume it suffices that only a limited number of features are supported in Markdown. By “features,” we mean the types of elements you can create with native Markdown. The limitation is a great feature, not a bug. R Markdown may not be the right format for you if you find these elements not enough for your writing: paragraphs, (section) headers, block quotations, code blocks, (numbered and unnumbered) lists, horizontal rules, tables, inline formatting (emphasis, strikeout, superscripts, subscripts, verbatim, and small caps text), LaTeX math expressions, equations, links, images, footnotes, citations, theorems, proofs, and examples. We believe this list of elements suffice for most technical and non-technical documents. It may not be impossible to support other types of elements in R Markdown, but you may start to lose the simplicity of Markdown if you wish to go that far.
Epictetus once said, “Wealth consists not in having great possessions, but in having few wants.” The spirit is also reflected in Markdown. If you can control your preoccupation with pursuing typesetting features, you should be much more efficient in writing the content and can become a prolific author. It is entirely possible to succeed with simplicity. Jung Jae-sung was a legendary badminton player with a remarkably simple playing style: he did not look like a talented player and was very short compared to other players, so most of the time you would just see him jump three feet off the ground and smash like thunder over and over again in the back court until he beats his opponents.
Please do not underestimate the customizability of R Markdown because of the simplicity of its syntax. In particular, Pandoc templates can be surprisingly powerful, as long as you understand the underlying technologies such as LaTeX and CSS, and are willing to invest time in the appearance of your output documents (reports, books, presentations, and/or websites). As one example, you may check out the PDF report of the 2017 Employer Health Benefits Survey. It looks fairly sophisticated, but was actually produced via bookdown(Xie 2016), which is an R Markdown extension. A custom LaTeX template and a lot of LaTeX tricks were used to generate this report. Not surprisingly, this very book that you are reading right now was also written in R Markdown, and its full source is publicly available in the GitHub repository https://github.com/rstudio/rmarkdown-book.
R Markdown documents are often portable in the sense that they can be compiled to multiple types of output formats. Again, this is mainly due to the simplified syntax of the authoring language, Markdown. The simpler the elements in your document are, the more likely that the document can be converted to different formats. Similarly, if you heavily tailor R Markdown to a specific output format (e.g., LaTeX), you are likely to lose the portability, because not all features in one format work in another format.
Last but not least, your computing results will be more likely to be reproducible if you use R Markdown (or other knitr-based source documents), compared to the manual cut-and-paste approach. This is because the results are dynamically generated from computer source code. If anything goes wrong or needs to be updated, you can simply fix or update the source code, compile the document again, and the results will be automatically updated. You can enjoy reproducibility and convenience at the same time.