template/book/syntax_exercises/009.md

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

1. Open a new or existing Markdown file where you want to add a reference.
2. Let's start with the simplest way to create a reference to another chapter. This is by directly linking it through the file path as shown in 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)

3. Try out another way of referencing by using a target header. Navigate to the chapter or section you want to reference and assign it an identifier using {ref} as shown in the example below. This could be either in the same markdown file, or a different file altogether.

(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...

4. Now, let's explore three different ways to reference this section or chapter! For the first method, we use the standard title text by calling the identifier as follows:

My favourite exercise was {ref}`exercise_1`.

This will display: My favourite exercise was {ref}exercise_1.

5. For the second method, we want to refer to the section using a custom title text. Try this out by placing the text that you want to be displayed within the `` and calling the identifier within the <> as follows:

My favourite exercise was {ref}`the first one <exercise_1>`.

This will display: My favourite exercise was {ref}the first one <exercise_1>.

6. The final method uses markdown syntax to also display a custom title text. Refer to the desired section once again, this time by putting the custom text within the [] and calling the identifier within the <> as shown below:

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

7. Now we will test our knowledge using an equation. Similar to the code below, create an equation using and identify it using a label within the brackets.

$$ F = m \cdot a$$ (eq:Newton)

This will display as follows:

F = m \cdot a (eq:Newton)

8. In this step, we will use the three referencing methods discussed above to reference this equation as follows:

Refer to Equation {eq}`eq:Newton`
Refer to the {eq}'above equation <eq:Newton>'
Refer to [this equation](eq:Newton)

These will display as:

Refer to Equation {eq}eq:Newton Refer to the {eq}'above equation eq:Newton' Refer to this equation

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

1. Once you have added your references, commit your changes to the repository.
2. Click the green Commit changes button.
3. Add a commit message.
4. 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?