12.3 Markdown extensions

The bookdown package expands upon the Markdown syntax outlined in Section 2.5, and provides additional powerful features that assist longer documents and academic writing.

12.3.1 Number and reference equations

Section 2.5.3 highlighted how equations can be created using LaTeX syntax within Markdown. To number equations, put them in the equation environments, and assign labels to them using the syntax (\#eq:label). Equation labels must start with the prefix eq: in bookdown. For example:

\begin{equation}
  E=mc^2
  (\#eq:emc)
\end{equation}

It renders the equation below (12.1):

\[\begin{equation} E=mc^2 \tag{12.1} \end{equation}\]

12.3.2 Theorems and proofs

Theorems and proofs provide environments that are commonly used within articles and books in mathematics. To write a theorem, you can use the syntax below:

```{theorem}
Here is my theorem.
```

For example:

Theorem 12.1 (Pythagorean theorem) For a right triangle, if \(c\) denotes the length of the hypotenuse and \(a\) and \(b\) denote the lengths of the other two sides, we have

\[a^2 + b^2 = c^2\]

Theorems can be numbered and cross-referenced, as you can see from Theorem 12.1. The proof environment behaves similarly to theorem environments but is unnumbered.

Variants of the theorem environments include: lemma, corollary, proposition, conjecture, definition, example, and exercise. Variants of the proof environments include remark and solution. The syntax for these environments is similar to the theorem environment, e.g., ```{lemma}.

12.3.3 Special headers

There are two special types of first-level headers than can be used in bookdown:

• A part can be created using # (PART) Part Title {-} before the chapters that belong to this part.

• Appendices # (APPENDIX) Appendix {-}: All chapters after this header will be treated as the appendix. The numbering style of these chapters will be A, B, C, etc., and sections will be numbered as A.1, A.2, and so on.

12.3.4 Text references

A text reference is a paragraph with a label. The syntax is (ref:label) text, where label is a unique identifier, and text is a Markdown paragraph. For example:

(ref:foo) Define a text reference **here**.

Then you can use (ref:foo) to refer to the full text. Text references can be used anywhere in the document, and are particularly useful when assigning a long caption to a figure or including Markdown formatting in a caption. For example:

Some text.

(ref:cool-plot) A boxplot of the data `iris` in **base** R.

```{r cool-plot, fig.cap='(ref:cool-plot)'}
boxplot(Sepal.Length ~ Species, data = iris)
```

12.3.5 Cross referencing

The bookdown package extends cross-referencing in R Markdown documents and allows section headers, tables, figures, equations, and theorems to be cross-referenced automatically. This only works for numbered environments, and therefore requires figures and tables to be assigned a label. Cross-references are made in the format \@ref(type:label), where label is the chunk label and type is the environment being referenced. As examples:

• Headers:

  # Introduction {#intro}
  
  This is Chapter \@ref(intro)

• Figures:

  See Figure \@ref(fig:cars-plot)
  
  ```{r cars-plot, fig.cap="A plot caption"}
  plot(cars)  # a scatterplot
  ```

• Tables:

  See Table \@ref(tab:mtcars)
  
  ```{r mtcars}
  knitr::kable(mtcars[1:5, 1:5], caption = "A caption")
  ```

• Theorems:

  See Theorem \@ref(thm:boring)
  
  ```{theorem, boring}
  Here is my theorem.
  ```

• Equations:

  See equation \@ref(eq:linear)
  
  \begin{equation}
  a + bx = c  (\#eq:linear)
  \end{equation}

Note that only alphanumeric characters (a-z, A-Z, 0-9), -, /, and : are allowed in these labels.