2.5 Markdown syntax | R Markdown: The Definitive Guide (2024)

2.5.1 Inline formatting

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 H₃PO₄). A pair of carets (^) produce a superscript (e.g., Cu^2+^ renders Cu²⁺).

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., ![alt text or image title](path/to/image). 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:

@Manual{R-base, title = {R: A Language and Environment for Statistical Computing}, author = {{R Core Team}}, organization = {R Foundation for Statistical Computing}, address = {Vienna, Austria}, year = {2017}, url = {https://www.R-project.org/},}

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 (2023)”) or [@R-base] (which generates “(R Core Team 2023)”) to reference the BibTeX entry. Pandoc will automatically generate 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.,

# First-level header## Second-level header### Third-level header

If you do not want a certain heading to be numbered, you can add {-} or {.unnumbered} after the heading, e.g.,

# Preface {-}

Unordered list items start with *, -, or +, and you can nest one list within another list by indenting the sub-list, e.g.,

- one item- one item- one item - one more item - one more item - one more item

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.,

1. the first item2. the second item3. the third item - one unordered item - one unordered item

The output does not look too much different with the Markdown source:

1. the first item
2. the second item
3. the third item
   • one unordered item
   • one unordered item

Blockquotes are written after >, e.g.,

> "I thoroughly disapprove of duels. If a man should challenge me, I would take him kindly and forgivingly by the hand and lead him to a quiet place and kill him.">> --- Mark Twain

The actual output (we customized the style for blockquotes in this book):

“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.,

```This text is displayed verbatim / preformatted```Or indent by four spaces: This text is displayed verbatim / preformatted

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?

In R, the character# indicates a comment.

And does “-” mean a bullet point below?

The result of 5- 3 is 2.

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:

\[f\left(k\right)=\binom{n}{k}p^k\left(1-p\right)^{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}$$

\[\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}$$

\[X = \begin{bmatrix}1 & x_{1}\\1 & x_{2}\\1 & x_{3}\end{bmatrix}\]

$$\Theta = \begin{pmatrix}\alpha & \beta\\\gamma & \delta\end{pmatrix}$$

\[\Theta = \begin{pmatrix}\alpha & \beta\\\gamma & \delta\end{pmatrix}\]

$$\begin{vmatrix}a & b\\c & d\end{vmatrix}=ad-bc$$

\[\begin{vmatrix}a & b\\c & d\end{vmatrix}=ad-bc\]