Exercise 11: Cross-referencing content

Exercise 11: 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.

Tip

Referencing elements properly ensures that readers can navigate your book more easily. More details can be found in the JupyterBook documentation.

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. Try this out by directly linking the chapter 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)

If you leave the text part empty, the title of the chapter you’re referring to will be used:

[](path/to/file.md)

Tip

If the chapter you’re referring to is in different directory than your chapter, you’ll need to refer it using relative parts. If the to be referenced chapter is in a subdirectory of the directory of the chapter, go deeper with subdirectory/ (e.g. <subdirectory>/<chapter in subdirectory>.md). If the to be referenced chapter is in another directory, move upwards with ../ (e.g. ../../<subdirectory>/<chapter which is located in a subdirectory two folders above the current page.md> )

  1. 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. Use the example below to test this out.

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

  1. 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 within brackets as shown in the example below. This could be once again in the same markdown file, or a different file in the same repository.

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

  1. 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`.

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

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

  1. 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 [] and calling the identifier within <> as shown below.

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

Referencing an Equation#

  1. Now we will test our knowledge using an equation (as implemented before in Exercise 9: Use equations). Similar to the code below, create an equation using $$ and identify it using a label within the brackets.

$$ F = m \cdot a$$ (eq:Newton)
(1)#\[ F = m \cdot a\]

  1. Refer to this equation by using {eq} and calling the identifier within the ``. This will automatically insert the number of the equation. You can add text as you did in exercise 6.

Refer to Equation {eq}`eq:Newton`

Alternatively, you can use the default [<text to display>](<identifier>).

Referencing a Table#

  1. Similar methods can also be used to refer to a table (as implemented before in Exercise 10: Create tables). Start by creating a table by copying the code below. The identifier is defined using :name:.

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

Column 1

Column 2

A

B

  1. Refer to the table like with custom text ‘My table’ and the number using {numref} and {number} as follows. You can add text as you did in exercise 6.

{numref}`My table {number} <tab-example>`

Alternatively, you get an automatic text ‘Table ‘ and the number when using {numref}`<tab-example>`. Or use {ref} to use the table name instead of number. Next to all of that you can use the default [<Eventually text to display, otherwise use title>](<table name>).

Referencing a Figure#

  1. This can also be done for a figure. Let’s add a figure as we learnt to do in Exercise 8, but this time adding an identifier using name:.

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

  1. Refer to the figure in the with custom text ‘Figure’ and the number using {numref} as follows. You can add text as you did in exercise 6.

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

Alternatively, you get an automatic text ‘Fig.’ and the number when using {numref}`<fig-example>`. Or use {ref} to use the figure name instead of number. Next to all of that you can use the default [<Eventually text to display, otherwise use title>](<figure name>).

Contents