2.6 Cross-references

We have explained how cross-references work for equations (Section 2.2.1), theorems (Section 2.2.2), figures (Section 2.4), and tables (Section 2.5). In fact, you can also reference sections using the same syntax \@ref(label), where label is the section ID. By default, Pandoc will generate an ID for all section headers, e.g., a section # Hello World will have an ID hello-world. We recommend you to manually assign an ID to a section header to make sure you do not forget to update the reference label after you change the section header. To assign an ID to a section header, simply add {#id} to the end of the section header. Further attributes of section headers can be set using standard Pandoc syntax.

When a referenced label cannot be found, you will see two question marks like ??, as well as a warning message in the R console when rendering the book.

You can also create text-based links using explicit or automatic section IDs or even the actual section header text.

  • If you are happy with the section header as the link text, use it inside a single set of square brackets:
  • There are two ways to specify custom link text:
    • [link text][Section header text], e.g., “non-English books” via [non-English books][Internationalization]
    • [link text](#ID), e.g., “Table stuff” via [Table stuff](#tables)

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

Cross-references still work even when we refer to an item that is not on the current page of the PDF or HTML output. For example, see Equation (2.1) and Figure 2.4.