12.3 Markdown extensions

Thebookdown package expands upon the Markdown syntax outlined in Section2.5, and provides additional powerful features that assist longer documents and academic writing.

12.3.1 Number and reference equations

Section2.5.3 highlighted how equations can be created using LaTeX syntax within Markdown. To number equations, put them in theequation environments, and assign labels to them using the syntax(\#eq:label). Equation labels must start with the prefixeq: inbookdown. 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, label, name="Theorem name"}Here is my theorem.```

For example:

Theorem 12.1 (Pythagorean theorem)For a right triangle, if\(c\) denotes the length of the hypotenuseand\(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 Theorem12.1. Theproof environment behaves similarly to theorem environments but is unnumbered.

Variants of thetheorem environments include:lemma,corollary,proposition,conjecture,definition,example,exercise, andhypothesis. The abbreviations for references (e.g. \@ref(lem:mylemma)) are respectivelylem,cor,prp,cnj,def,exm,exr, andhyp.Variants of theproof environments includeremark andsolution. The syntax for these environments is similar to thetheorem environment, e.g.,```{lemma}.

12.3.3 Special headers

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

  • 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 beA,B,C, etc., and sections will be numbered asA.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, wherelabel is a unique identifier, andtext 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

Thebookdown 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), wherelabel is the chunk label andtype 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.