2.2 Markdown extensions by bookdown
Although Pandoc’s Markdown is much richer than the original Markdown syntax, it still lacks a number of things that we may need for academic writing. For example, it supports math equations, but you cannot number and reference equations in multi-page HTML or EPUB output. We have provided a few Markdown extensions in bookdown to fill the gaps.
2.2.1 Number and reference equations
To number and refer to equations, put them in the equation environments and assign labels to them using the syntax (\#eq:label), e.g.,
\begin{equation}
f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
(\#eq:binom)
\end{equation} It renders the equation below:
\[\begin{equation} f\left(k\right)=\binom{n}{k}p^k\left(1-p\right)^{n-k} \tag{2.1} \end{equation}\]
You may refer to it using \@ref(eq:binom), e.g., see Equation (2.1).
eq: in bookdown. All labels in bookdown must only contain alphanumeric characters, :, -, and/or /. Equation references work best for LaTeX/PDF output, and they are not well supported in Word output or e-books. For HTML output, bookdown can only number the equations with labels. Please make sure equations without labels are not numbered by either using the equation* environment or adding \nonumber or \notag to your equations. The same rules apply to other math environments, such as eqnarray, gather, align, and so on (e.g., you can use the align* environment).
We demonstrate a few more math equation environments below. Here is an unnumbered equation using the equation* environment:
\begin{equation*}
\frac{d}{dx}\left( \int_{a}^{x} f(u)\,du\right)=f(x)
\end{equation*} \[\begin{equation*} \frac{d}{dx}\left( \int_{a}^{x} f(u)\,du\right)=f(x) \end{equation*}\]
Below is an align environment (2.2):
\begin{align}
g(X_{n}) &= g(\theta)+g'({\tilde{\theta}})(X_{n}-\theta) \notag \\
\sqrt{n}[g(X_{n})-g(\theta)] &= g'\left({\tilde{\theta}}\right)
\sqrt{n}[X_{n}-\theta ] (\#eq:align)
\end{align} \[\begin{align} g(X_{n}) &= g(\theta)+g'({\tilde{\theta}})(X_{n}-\theta) \notag \\ \sqrt{n}[g(X_{n})-g(\theta)] &= g'\left({\tilde{\theta}}\right) \sqrt{n}[X_{n}-\theta ] \tag{2.2} \end{align}\]
You can use the split environment inside equation so that all lines share the same number (2.3). By default, each line in the align environment will be assigned an equation number. We suppressed the number of the first line in the previous example using \notag. In this example, the whole split environment was assigned a single number.
\begin{equation}
\begin{split}
\mathrm{Var}(\hat{\beta}) & =\mathrm{Var}((X'X)^{-1}X'y)\\
& =(X'X)^{-1}X'\mathrm{Var}(y)((X'X)^{-1}X')'\\
& =(X'X)^{-1}X'\mathrm{Var}(y)X(X'X)^{-1}\\
& =(X'X)^{-1}X'\sigma^{2}IX(X'X)^{-1}\\
& =(X'X)^{-1}\sigma^{2}
\end{split}
(\#eq:var-beta)
\end{equation} \[\begin{equation} \begin{split} \mathrm{Var}(\hat{\beta}) & =\mathrm{Var}((X'X)^{-1}X'y)\\ & =(X'X)^{-1}X'\mathrm{Var}(y)((X'X)^{-1}X')'\\ & =(X'X)^{-1}X'\mathrm{Var}(y)X(X'X)^{-1}\\ & =(X'X)^{-1}X'\sigma^{2}IX(X'X)^{-1}\\ & =(X'X)^{-1}\sigma^{2} \end{split} \tag{2.3} \end{equation}\]
2.2.2 Theorems and proofs
Theorems and proofs are commonly used in articles and books in mathematics. However, please do not be misled by the names: a “theorem” is just a numbered/labeled environment, and it does not have to be a mathematical theorem (e.g., it can be an example irrelevant to mathematics). Similarly, a “proof” is an unnumbered environment. In this section, we always use the general meanings of a “theorem” and “proof” unless explicitly stated.
In bookdown, the types of theorem environments supported are in Table 2.1. To write a theorem, you can use the syntax below:
```{theorem}
Here is my theorem.
```| Environment | Printed Name | Label Prefix |
|---|---|---|
| theorem | Theorem | thm |
| lemma | Lemma | lem |
| corollary | Corollary | cor |
| proposition | Proposition | prp |
| conjecture | Conjecture | cnj |
| definition | Definition | def |
| example | Example | exm |
| exercise | Exercise | exr |
To write other theorem environments, replace ```{theorem} with other environment names in Table 2.1, e.g., ```{lemma}.
A theorem can have a name option so its name will be printed, e.g.,
```{theorem, name="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$$
```If you want to refer to a theorem, you should label it. The label can be written after ```{theorem, e.g.,
```{theorem, label="foo"}
A labeled theorem here.
```The label option can be implicit, e.g., the following theorem has the label bar:
```{theorem, bar}
A labeled theorem here.
```After you label a theorem, you can refer to it using the syntax \@ref(prefix:label). See the column Label Prefix in Table 2.1 for the value of prefix for each environment. For example, we have a labeled and named theorem below, and \@ref(thm:pyth) gives us its theorem number 2.1:
```{theorem, pyth, name="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$$
```Theorem 2.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\]The proof environments currently supported are proof, remark, and solution. The syntax is similar to theorem environments, and proof environments can also be named. The only difference is that since they are unnumbered, you cannot reference them.
We have tried to make all these theorem and proof environments work out of the box, no matter if your output is PDF, HTML, or EPUB. If you are a LaTeX or HTML expert, you may want to customize the style of these environments anyway (see Chapter 4). Customization in HTML is easy with CSS, and each environment is enclosed in <div></div> with the CSS class being the environment name, e.g., <div class="lemma"></div>. For LaTeX output, we have predefined the style to be definition for environments definition, example, and exercise, and remark for environments proof and remark. All other environments use the plain style. The style definition is done through the \theoremstyle{} command of the amsthm package.
Theorems are numbered by chapters by default. If there are no chapters in your document, they are numbered by sections instead. If the whole document is unnumbered (the output format option number_sections = FALSE), all theorems are numbered sequentially from 1, 2, …, N. LaTeX supports numbering one theorem environment after another, e.g., let theorems and lemmas share the same counter. This is not supported for HTML/EPUB output in bookdown. You can change the numbering scheme in the LaTeX preamble by defining your own theorem environments, e.g.,
\newtheorem{theorem}{Theorem}
\newtheorem{lemma}[theorem]{Lemma}When bookdown detects \newtheorem{theorem} in your LaTeX preamble, it will not write out its default theorem definitions, which means you have to define all theorem environments by yourself. For the sake of simplicity and consistency, we do not recommend that you do this. It can be confusing when your Theorem 18 in PDF becomes Theorem 2.4 in HTML.
Theorem and proof environments will be hidden if the chunk option echo is set to FALSE. To make sure they are always shown, you may add the chunk option echo=TRUE, e.g.,
```{theorem, echo=TRUE}
Here is my theorem.
```Below we show more examples4 of the theorem and proof environments, so you can see the default styles in bookdown.
Definition 2.1 The characteristic function of a random variable \(X\) is defined by
\[\varphi _{X}(t)=\operatorname {E} \left[e^{itX}\right], \; t\in\mathcal{R}\]Example 2.1 We derive the characteristic function of \(X\sim U(0,1)\) with the probability density function \(f(x)=\mathbf{1}_{x \in [0,1]}\).
\[\begin{equation*} \begin{split} \varphi _{X}(t) &= \operatorname {E} \left[e^{itX}\right]\\ & =\int e^{itx}f(x)dx\\ & =\int_{0}^{1}e^{itx}dx\\ & =\int_{0}^{1}\left(\cos(tx)+i\sin(tx)\right)dx\\ & =\left.\left(\frac{\sin(tx)}{t}-i\frac{\cos(tx)}{t}\right)\right|_{0}^{1}\\ & =\frac{\sin(t)}{t}-i\left(\frac{\cos(t)-1}{t}\right)\\ & =\frac{i\sin(t)}{it}+\frac{\cos(t)-1}{it}\\ & =\frac{e^{it}-1}{it} \end{split} \end{equation*}\]
Note that we used the fact \(e^{ix}=\cos(x)+i\sin(x)\) twice.Lemma 2.1 For any two random variables \(X_1\), \(X_2\), they both have the same probability distribution if and only if
\[\varphi _{X_1}(t)=\varphi _{X_2}(t)\]Theorem 2.2 If \(X_1\), …, \(X_n\) are independent random variables, and \(a_1\), …, \(a_n\) are some constants, then the characteristic function of the linear combination \(S_n=\sum_{i=1}^na_iX_i\) is
\[\varphi _{S_{n}}(t)=\prod_{i=1}^n\varphi _{X_i}(a_{i}t)=\varphi _{X_{1}}(a_{1}t)\cdots \varphi _{X_{n}}(a_{n}t)\]Proof. The characteristic function of \(X\sim\mathrm{Pois}(\lambda)\) is \(\varphi _{X}(t)=e^{\lambda (e^{it}-1)}\). Let \(P_n=\sum_{i=1}^nX_i\). We know from Theorem 2.2 that
\[\begin{equation*} \begin{split} \varphi _{P_{n}}(t) & =\prod_{i=1}^n\varphi _{X_i}(t) \\ & =\prod_{i=1}^n e^{\lambda_i (e^{it}-1)} \\ & = e^{\sum_{i=1}^n \lambda_i (e^{it}-1)} \end{split} \end{equation*}\]
This is the characteristic function of a Poisson random variable with the parameter \(\lambda=\sum_{i=1}^n \lambda_i\). From Lemma 2.1, we know the distribution of \(P_n\) is \(\mathrm{Pois}(\sum_{i=1}^n\lambda_i)\).Corollary 2.1 The characteristic function of the sum of two independent random variables \(X_1\) and \(X_2\) is the product of characteristic functions of \(X_1\) and \(X_2\), i.e.,
\[\varphi _{X_1+X_2}(t)=\varphi _{X_1}(t) \varphi _{X_2}(t)\]Solution. Applying Theorem 2.2, we have
\[\varphi _{\bar{X}}(t)=\prod_{i=1}^n \varphi _{X_i}\left(\frac{t}{n}\right)=\left[\varphi _{X}\left(\frac{t}{n}\right)\right]^n.\]2.2.3 Special headers
There are a few special types of first-level headers that will be processed differently in bookdown. The first type is an unnumbered header that starts with the token (PART). This kind of headers are translated to part titles. If you are familiar with LaTeX, this basically means \part{}. When your book has a large number of chapters, you may want to organize them into parts, e.g.,
# (PART) Part I {-}
# Chapter One
# Chapter Two
# (PART) Part II {-}
# Chapter ThreeA part title should be written right before the first chapter title in this part. You can use (PART\*) (the backslash before * is required) instead of (PART) if a part title should not be numbered.
The second type is an unnumbered header that starts with (APPENDIX), indicating that all chapters after this header are appendices, e.g.,
# Chapter One
# Chapter Two
# (APPENDIX) Appendix {-}
# Appendix A
# Appendix BThe numbering style of appendices will be automatically changed in LaTeX/PDF and HTML output (usually in the form A, A.1, A.2, B, B.1, …). This feature is not available to e-books or Word output.
2.2.4 Text references
You can assign some text to a label and reference the text using the label elsewhere in your document. This can be particularly useful for long figure/table captions (Section 2.4 and 2.5), in which case you normally will have to write the whole character string in the chunk header (e.g., fig.cap = "A long long figure caption.") or your R code (e.g., kable(caption = "A long long table caption.")). It is also useful when these captions contain special HTML or LaTeX characters, e.g., if the figure caption contains an underscore, it works in the HTML output but may not work in LaTeX output because the underscore must be escaped in LaTeX.
The syntax for a text reference is (ref:label) text, where label is a unique label5 throughout the document for text. It must be in a separate paragraph with empty lines above and below it. The paragraph must not be wrapped into multiple lines, and should not end with a white space. For example,
(ref:foo) Define a text reference **here**. Then you can use (ref:foo) in your figure/table captions. The text can contain anything that Markdown supports, as long as it is one single paragraph. Here is a complete example:
A normal paragraph.
(ref:foo) A scatterplot of the data `cars` using **base** R graphics.
```{r foo, fig.cap='(ref:foo)'}
plot(cars) # a scatterplot
```Text references can be used anywhere in the document (not limited to figure captions). It can also be useful if you want to reuse a fragment of text in multiple places.
Some examples are adapted from the Wikipedia page https://en.wikipedia.org/wiki/Characteristic_function_(probability_theory)↩︎
You may consider using the code chunk labels.↩︎