Understanding Cross-References in Bookdown Documents

Introduction

Bookdown is a popular package used to create documents from R Markdown files. It provides an efficient way to generate PDF, HTML, and other document formats from R Markdown files. One of the key features of bookdown is its ability to handle cross-references between different sections of a document.

In this article, we will explore how to create cross-references in bookdown documents, specifically when using the knitr::read_chunk function to include chunks from other documents.

Setting Up Bookdown

Before diving into cross-references, let’s set up a basic bookdown document. Create a new file called force.Rmd with the following content:

---
title: "Force"
author: "Your Name"
date: "`r Sys.Date()`"
output:
  pdf_document:
    figsdir: "./figures"
    titlepage: true
    latex_engine: "xelatex"
fig_caption: yes
---

## Introduction

In order to cross-reference figures in bookdown, the figure has to be put in a figure environment to generate the figure number.

### Creating a Figure Environment

To create a figure environment, we need to use the `fig.cap` option for code chunks. This will generate a caption for the figure that can be used as a reference later on.

```markdown
```{r}
knitr::read_chunk("plots.R")

fig.cap = "Figure 1: The First Plot"


## Cross-Referencing Figures

Now that we have created a figure environment with a caption, we can cross-reference it in our document. To do this, we need to use the `@ref(fig:x)` syntax, where `x` is the label of the figure.

However, when using `knitr::read_chunk`, the chunk labels are not automatically added to the document. Instead, they need to be manually specified.

```markdown
```{r}
knitr::read_chunk("plots.R")

fig.cap = "Figure 1: The First Plot"
chunk_label = "t1-1"


## Creating a Figure Environment in the Original Document

To create a figure environment in the original document, we need to specify the `fig.cap` option for each code chunk.

```markdown
```{r}
knitr::read_chunk("plots.R")


## Using Cross-References

Now that we have created a figure environment and specified the chunk labels, we can use cross-references in our document.

```markdown
### Figure 1: The First Plot

This is the first plot.

### Figure 2: The Second Plot

This is the second plot.

To create a cross-reference to Figure 1, we can use the following syntax:

@ref(fig:t1-1)

However, since our document does not have a figure environment for t1-1, this will not work.

Solution: Specifying the Chunk Label

One solution is to specify the chunk label manually. We can do this by adding the chunk_label option to each code chunk.

```{r}
knitr::read_chunk("plots.R")


By specifying the chunk label manually, we can create a cross-reference to `Figure 1`.

## Creating Cross-References with Chunk Labels

To create cross-references with chunk labels, we need to use the following syntax:

`@ref(fig:chunk_label)`

Where `chunk_label` is the label of the figure.

```markdown
### Figure 1: The First Plot

This is the first plot.

### @ref(fig:t1-1)

This will link to the cross-reference for `Figure 1`.

Conclusion

In this article, we have explored how to create cross-references in bookdown documents using chunk labels. We have also discussed the importance of specifying figure captions and chunk labels manually.

By following these steps, you can create cross-references that link to specific figures in your document.

Additional Tips

Make sure to specify the chunk label manually when creating code chunks.
Use the fig.cap option to generate a caption for each figure.
Specify the chunk_label option when creating code chunks to create cross-references later on.

Last modified on 2023-07-23