Chapter 9: A Minimal Book Example

9.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\).

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

9.1.2 Render book

You can render the HTML version of this example book without changing anything:

  1. Find the Build pane in the RStudio IDE, and

  2. 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/.

9.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()

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

9.2.1 A section

All chapter sections start with a second-level (##) or higher heading followed by your section title, like the sections above and below here. You can have as many as you want within a chapter.

An unnumbered section

Chapters and sections are numbered by default. To un-number a heading, add a {.unnumbered} or the shorter {-} at the end of the heading, like in this section.

9.3 Cross-references

Cross-references make it easier for your readers to find and link to elements in your book.

9.3.1 Chapters and sub-chapters

There are two steps to cross-reference any heading:

  1. 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}.
  2. Next, reference the labeled heading anywhere in the text using \@ref(nice-label); for example, please see Chapter 9.3.

9.3.2 Captioned figures and tables

Figures and tables with captions can also be cross-referenced from elsewhere in your book using \@ref(fig:chunk-label) and \@ref(tab:chunk-label), respectively.

See Figure 9.1.

par(mar = c(4, 4, .1, .1))
plot(pressure, type = 'b', pch = 19)
Plot with connected points showing that vapor pressure of mercury increases exponentially as temperature increases.

Fig. 9.1: Here is a nice figure!

Don’t miss Table 9.1.

knitr::kable(
  head(pressure, 10), caption = 'Here is a nice table!',
  booktabs = TRUE
)
Tab. 9.1: Here is a nice table!
temperature pressure
0 0.0002
20 0.0012
40 0.0060
60 0.0300
80 0.0900
100 0.2700
120 0.7500
140 1.8500
160 4.2000
180 8.8000

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

9.5 Footnotes and citations

9.5.1 Footnotes

Footnotes are put inside the square brackets after a caret ^[]. Like this one 3.

9.5.2 Citations

Reference items in your bibliography file(s) using @key.

For example, we are using the bookdown package1 (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 knitr2 (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 RStudio Visual Markdown Editor can also make it easier to insert citations: https://rstudio.github.io/visual-markdown-editing/#/citations

9.6 Blocks

9.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{9.1} \end{equation}\]

You may refer to using \@ref(eq:binom), like see Equation (9.1).

9.6.2 Theorems and proofs

Labeled theorems can be referenced in text using \@ref(thm:tri), for example, check out this smart theorem 9.1.

Theorem 9.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.

9.6.3 Callout blocks

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

9.7 Sharing your book

9.7.1 Publishing

HTML books can be published online, see: https://bookdown.org/yihui/bookdown/publishing.html

9.7.2 404 pages

By default, users will be directed to a 404 page if they try to access a webpage that cannot be found. If you’d like to customize your 404 page instead of using the default, you may add either a _404.Rmd or _404.md file to your project root and use code and/or Markdown syntax.

9.7.3 Metadata for sharing

Bookdown HTML books will provide HTML metadata for social sharing on platforms like Twitter, Facebook, and LinkedIn, using information you provide in the index.Rmd YAML. To setup, set the url for your book and the path to your cover-image file. Your book’s title and description are also used.

This gitbook uses the same social sharing data across all chapters in your book- all links shared will look the same.

Specify your book’s source repository on GitHub using the edit key under the configuration options in the _output.yml file, which allows users to suggest an edit by linking to a chapter’s source file.

Read more about the features of this output format here:

https://pkgs.rstudio.com/bookdown/reference/gitbook.html

Or use:

?bookdown::gitbook

references

1.
Xie, Y. Bookdown: Authoring Books and Technical Documents with r Markdown. (2023).
2.
Xie, Y. Dynamic Documents with R and Knitr. (Chapman; Hall/CRC, Boca Raton, Florida, 2015).

  1. This is a footnote.↩︎