42 Bookdown cheat sheet

Here’s where I park little examples for myself about bookdown mechanics that I keep forgetting.

The bookdown book: https://bookdown.org/yihui/bookdown/

42.1 Heading blah blah

42.2 About labelling things

You can label chapter and section titles using {#label} after them, e.g., we can reference Section 42.2. If you do not manually label them, there will be automatic labels anyway, e.g., this reference to the unlabelled heading 42.1 uses the automatically generated label \@ref(heading-blah-blah).

42.3 Cross-references

Add an explicit label by adding {#label} to the end of the section header. If you know you’re going to refer to something, this is probably a good idea.

To refer to in a chapter- or section-number-y way, use \@ref(label).

• \@ref(install-git) example: In chapter 6 we explain how to install Git.

If you are happy with the section header as the link text, use it inside a single set of square brackets:

• [A picture is worth a thousand words]: example “A picture is worth a thousand words” via A picture is worth a thousand words

There are two ways to specify custom link text:

• [link text][Section header text], e.g., “pic = 1000 words” via pic = 1000 words
• [link text](#label), e.g., “RStudio, meet Git” via RStudio, meet Git

The Pandoc documentation provides more details on automatic section IDs and implicit header references.

42.4 Figures, tables, citations

Figures and tables with captions will be placed in figure and table environments, respectively.

par(mar = c(4, 4, .1, .1))
plot(pressure, type = 'b', pch = 19)

Figure 42.1: Here is a nice figure!

Reference a figure by its code chunk label with the fig: prefix, e.g., see Figure 42.1. Similarly, you can reference tables generated from knitr::kable(), e.g., see Table 42.1.

knitr::kable(
  head(iris, 20), caption = 'Here is a nice table!',
  booktabs = TRUE
)

Table 42.1: Here is a nice table!

Sepal.Length	Sepal.Width	Petal.Length	Petal.Width	Species
5.1	3.5	1.4	0.2	setosa
4.9	3.0	1.4	0.2	setosa
4.7	3.2	1.3	0.2	setosa
4.6	3.1	1.5	0.2	setosa
5.0	3.6	1.4	0.2	setosa
5.4	3.9	1.7	0.4	setosa
4.6	3.4	1.4	0.3	setosa
5.0	3.4	1.5	0.2	setosa
4.4	2.9	1.4	0.2	setosa
4.9	3.1	1.5	0.1	setosa
5.4	3.7	1.5	0.2	setosa
4.8	3.4	1.6	0.2	setosa
4.8	3.0	1.4	0.1	setosa
4.3	3.0	1.1	0.1	setosa
5.8	4.0	1.2	0.2	setosa
5.7	4.4	1.5	0.4	setosa
5.4	3.9	1.3	0.4	setosa
5.1	3.5	1.4	0.3	setosa
5.7	3.8	1.7	0.3	setosa
5.1	3.8	1.5	0.3	setosa

You can write citations, too. For example, we are using the bookdown package (Xie 2024) in this sample book, which was built on top of R Markdown and knitr (Xie 2015).

42.5 How the square bracket links work

Context: you prefer to link with text, not a chapter or section number.

• GOOD! Here’s a link to Contributors.
• BAD. You can see contributors in 2.

Facts and vocabulary

• Each chapter is a file. These files should begin with the chapter title using a level-one header, e.g., # Chapter Title.
• A chapter can be made up of sections, indicated by lower-level headers, e.g., ## A section within the chapter.
• There are three ways to address a section when creating links within your book:
  • Explicit identifier: In # My header {#foo} the explicit identifier is foo.
  • Automatically generated identifier: my-header is the auto-identifier for # My header. Pandoc creates auto-identifiers according to rules laid out in Extension: auto_identifiers.
  • The header text, e.g., My header be used verbatim as an implicit header reference. See Extension: implicit_header_references for more.
• All 3 forms can be used to create cross-references but you build the links differently.
• Advantage of explicit identification: You are less likely to update the section header and then forget to make matching edits to references elsewhere in the book.

How to make text-based links using explicit identifiers, automatic identifiers, and implicit references:

• Use implicit reference alone to get a link where the text is exactly the section header:
  • [Introduce yourself to Git] Introduce yourself to Git
  • [Success and operating systems] Success and operating systems
• You can provide custom text for the link with all 3 methods of addressing a section:
  • Implicit header reference: [link text][Recommended Git clients] link text
    
  • Explicit identifier: [hello git! I'm Jenny](#hello-git) hello git! I’m Jenny
  • Automatic identifier: [Any text you want](#recommended-git-clients) Any text you want