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, as well as links.

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

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 {ref}exercise_1.
Specifying a custom title text:
```
My favourite exercise was {ref}`the first one <exercise_1>`.
```
This will display: My favourite exercise was {ref}the first one <exercise_1>.
Using Markdown syntax:
```
My favourite exercise was [this one](exercise_1).
```
This will display: My favourite exercise was this one.

These three referencing methods can also be used for referencing equations, tables and figures.

2. Referencing an Equation

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


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

You can then reference this equation using:

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 {numref}:

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 {numref}:

Figure {numref}`fig-example`

5. Referencing a Link

To reference a link, use the following syntax:

[Text to display](https://teachbooks.github.io/template/)

For example, you can write:

Here is the [link to the template](https://teachbooks.github.io/template/).

This wil display: Here is the link to the template.

6. 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, table or figure in your book?
- How do you reference a link?

3.6 KiB Raw Blame History