D Bookdown
D.1 About
This is a sample book written in Markdown. You can use anything that Pandoc’s Markdown supports; for example, a math equation \(a^2 + b^2 = c^2\).
D.1.1 Usage
Each bookdown chapter is an .Rmd file, and each .Rmd file can contain one (and only one) chapter. A chapter must start with a first-level heading: # A good chapter
, and can contain one (and only one) first-level heading.
Use second-level and higher headings within chapters like: ## A short section
or ### An even shorter section
.
The index.Rmd
file is required, and is also your first book chapter. It will be the homepage when you render the book.
D.1.2 Render book
You can render the HTML version of this example book without changing anything:
Find the Build pane in the RStudio IDE, and
Click on Build Book, then select your output format, or select “All formats” if you’d like to use multiple formats from the same book source files.
Or build the book from the R console:
bookdown::render_book()
To render this example to PDF as a bookdown::pdf_book
, you’ll need to install XeLaTeX. You are recommended to install TinyTeX (which includes XeLaTeX): https://yihui.org/tinytex/.
D.1.3 Preview book
As you work, you may start a local server to live preview this HTML book. This preview will update as you edit the book when you save individual .Rmd files. You can start the server in a work session by using the RStudio add-in “Preview book”, or from the R console:
bookdown::serve_book()
D.2 Hello bookdown
All chapters start with a first-level heading followed by your chapter title, like the line above. There should be only one first-level heading (#
) per .Rmd file.
D.3 Cross-references
Cross-references make it easier for your readers to find and link to elements in your book.
D.3.1 Chapters and sub-chapters
There are two steps to cross-reference any heading:
- Label the heading:
# Hello world {#nice-label}
.- Leave the label off if you like the automated heading generated based on your heading title: for example,
# Hello world
=# Hello world {#hello-world}
. - To label an un-numbered heading, use:
# Hello world {-#nice-label}
or{# Hello world .unnumbered}
.
- Leave the label off if you like the automated heading generated based on your heading title: for example,
- Next, reference the labeled heading anywhere in the text using
\@ref(nice-label)
; for example, please see Chapter D.3.- If you prefer text as the link instead of a numbered reference use: any text you want can go here.
D.4 Parts
You can add parts to organize one or more book chapters together. Parts can be inserted at the top of an .Rmd file, before the first-level chapter heading in that same file.
Add a numbered part: # (PART) Act one {-}
(followed by # A chapter
)
Add an unnumbered part: # (PART\*) Act one {-}
(followed by # A chapter
)
Add an appendix as a special kind of un-numbered part: # (APPENDIX) Other stuff {-}
(followed by # A chapter
). Chapters in an appendix are prepended with letters instead of numbers.
D.5 Footnotes and citations
D.5.1 Footnotes
Footnotes are put inside the square brackets after a caret ^[]
. Like this one 1.
D.5.2 Citations
Reference items in your bibliography file(s) using @key
.
For example, we are using the bookdown package2 (check out the last code chunk in index.Rmd to see how this citation key was added) in this sample book, which was built on top of R Markdown and knitr3 (this citation was added manually in an external file book.bib).
Note that the .bib
files need to be listed in the index.Rmd with the YAML bibliography
key.
The bs4_book
theme makes footnotes appear inline when you click on them. In this example book, we added csl: chicago-fullnote-bibliography.csl
to the index.Rmd
YAML, and include the .csl
file. To download a new style, we recommend: https://www.zotero.org/styles/
The RStudio Visual Markdown Editor can also make it easier to insert citations: https://rstudio.github.io/visual-markdown-editing/#/citations
D.6 Blocks
D.6.1 Equations
Here is an equation.
\[\begin{equation} f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k} \tag{D.1} \end{equation}\]
You may refer to using \@ref(eq:binom)
, like see Equation (D.1).
D.6.2 Theorems and proofs
Labeled theorems can be referenced in text using \@ref(thm:tri)
, for example, check out this smart theorem D.1.
Theorem D.1 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\]
Read more here https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html.
D.6.3 Callout blocks
The bs4_book
theme also includes special callout blocks, like this .rmdnote
.
You can use markdown inside a block.
head(beaver1, n = 5)
#> day time temp activ
#> 1 346 840 36.33 0
#> 2 346 850 36.34 0
#> 3 346 900 36.35 0
#> 4 346 910 36.42 0
#> 5 346 920 36.55 0
It is up to the user to define the appearance of these blocks for LaTeX output.
You may also use: .rmdcaution
, .rmdimportant
, .rmdtip
, or .rmdwarning
as the block name.
The R Markdown Cookbook provides more help on how to use custom blocks to design your own callouts: https://bookdown.org/yihui/rmarkdown-cookbook/custom-blocks.html