Exercise 9: Cross-referencing content

In this exercise, you will learn how to create references to other parts of your book, such as chapters, sections, equations, tables, and figures.

::::::{topic} Exercise objective Can you create internal references to other sections, equations, tables, and figures? ::::::

Referencing elements properly ensures that readers can navigate your book more easily. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/references.html).

1. Referencing a Chapter or Section

To create a reference to another chapter or section, use the following syntax:

[Text to display](path/to/file.md)

For example, if you want to link to Exercise 7, you can write:

[Go to Exercise 7](../exercises/007.md)

Alternatively, you can use {ref} to reference a section with a target header.

First, define the section you want to reference by assigning it an identifier:

(exercise_1)=
# Exercise 1: First file edit

Let's start with the most basic edit: add some text to a file and see that the website is updated...

Then, you can reference this section in three ways:

Using the standard title text:
```
My favourite exercise was {ref}`exercise_1`.
```
This will display: My favourite exercise was Exercise 1: First file edit.
Specifying a custom title text:
```
My favourite exercise was {ref}`the first one <exercise_1>`.
```
This will display: My favourite exercise was the first one.
Using Markdown syntax:
```
My favourite exercise was [this one](exercise_1).
```
This will display: My favourite exercise was this one.

2. Referencing an Equation

To reference an equation, you need to define a label using {eq} and refer to it elsewhere in your text:

```{math}
:label: eq-example
E = mc^2


You can then reference this equation using:

```md
Equation {eq}`eq-example`

3. Referencing a Table

To reference a table, assign a label when defining it:

```{table} Example Table
:label: tab-example
| Column 1 | Column 2 |
|----------|----------|
| A        | B        |


And refer to it using:

```md
Table {numref}`tab-example`

4. Referencing a Figure

To reference a figure, label it when inserting it:

```{figure} figures/example.png
---
width: 80%
align: center
name: fig-example
---
Example figure.


And refer to it using:

```md
Figure {numref}`fig-example`

5. Commit Your Changes

Once you have added your references, commit your changes to the repository.
Click the green Commit changes button.
Add a commit message.
View your changes using the Actions tab and check if they appear correctly.

:class: note

Before moving on to the next exercise, make sure you understand the following:
- How do you reference another chapter or section?
- How do you create a reference to an equation?
- How can you refer to a table or a figure in your book?

3 KiB Raw Blame History