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?
::::::

```{tip}
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).
```

## 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:

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

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

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

3. If we want to refer to a section within the same file, we can use local refencing by directly inputting the name of the required section. For example: [Jump to the next section](#referencing-an-equation)

```md
[Jump to the next section](#referencing-an-equation)
```


4. 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 once again in the same markdown file, or a different file in the same repository.

```md
(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...
```
5. 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. This will display: My favourite exercise was {ref}`exercise_1`.

  ```md
  My favourite exercise was {ref}`exercise_1`.
  ```


6. 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 `` and calling the identifier within <>. 
This will display: My favourite exercise was {ref}`the first one <exercise_1>`.

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


7. The last 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. This will display: My favourite exercise was [this one](exercise_1).


  ```md
  My favourite exercise was [this one](exercise_1).
  ```


## Referencing an Equation

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


  ```md

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

  ```

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

8. To refer to this equation we need to use `{eq}` and call the identifier within the `` to achieve: Refer to Equation {eq}`eq:Newton`.

```md
Refer to Equation {eq}`eq:Newton`
```


## Referencing a Table

9. Similar methods can also be used to refer to a table. Start by creating a table by copying the code below. The identifier is defined using `:name:`.

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


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

10. Refer to the table like {numref}`Table {number} <tab-example>` using {numref} and {number} as follows:


```md
{numref}`Table {number} <tab-example>`
```


## Referencing a Figure

11. This can also be done for a figure. Let's add a figure as we learnt to do in [Exercise 7](007.md), but this time adding an identifier using `name:`.

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

12. Refer to the figure in the format {numref}`Figure {number} <fig-example>` using `{numref}` as follows:

```md
{numref}`Figure {number} <fig-example>`
```

## Referencing a Link

13. Finally, lets reference a link, using the following syntax:

```md
[Text to display](url)
```
For example, you can use the code below to display: Here is the [link to the template](https://teachbooks.github.io/template/).


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


14. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.

15. Add a commit message.

16. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).

17. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.


```{admonition} Check your understanding
: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?