mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-13 06:35:52 +00:00
163 lines
4.8 KiB
Markdown
163 lines
4.8 KiB
Markdown
# 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).
|
|
```
|
|
|
|
## 1. Referencing a Chapter or Section
|
|
|
|
1. Open the Markdown file where you want to add a reference.
|
|
2. Lets start with the simplest way to create a reference to another chapter or section. 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)
|
|
```
|
|
|
|
If you leave the text part empty, the title of the chapter you're referring to will be used:
|
|
|
|
```md
|
|
[](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>` )
|
|
```
|
|
|
|
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.
|
|
|
|
```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...
|
|
```
|
|
4. Now, lets explore three different ways to reference this section! For the first method, we use the standard title text by calling the identifier as follows:
|
|
|
|
```md
|
|
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:
|
|
|
|
```md
|
|
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:
|
|
|
|
|
|
```md
|
|
My favourite exercise was [this one](exercise_1).
|
|
```
|
|
This will display: My favourite exercise was [this one](exercise_1).
|
|
|
|
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}`:
|
|
|
|
```md
|
|
|
|
```{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:
|
|
|
|
```md
|
|
```{table} Example Table
|
|
:label: tab-example
|
|
| Column 1 | Column 2 |
|
|
|----------|----------|
|
|
| A | B |
|
|
```
|
|
```
|
|
|
|
And refer to it using `{numref}`:
|
|
|
|
```md
|
|
Table {numref}`tab-example`
|
|
```
|
|
|
|
|
|
## 4. Referencing a Figure
|
|
|
|
To reference a figure, label it when inserting it:
|
|
|
|
```md
|
|
```{figure} figures/example.png
|
|
---
|
|
width: 80%
|
|
align: center
|
|
name: fig-example
|
|
---
|
|
Example figure.
|
|
```
|
|
```
|
|
|
|
And refer to it using `{numref}`:
|
|
|
|
```md
|
|
Figure {numref}`fig-example`
|
|
```
|
|
|
|
## 5. Referencing a Link
|
|
|
|
To reference a link, use the following syntax:
|
|
|
|
```md
|
|
[Text to display](https://teachbooks.github.io/template/)
|
|
```
|
|
For example, you can write:
|
|
|
|
```md
|
|
Here is the [link to the template](https://teachbooks.github.io/template/).
|
|
```
|
|
|
|
This wil display: Here is the [link to the template](https://teachbooks.github.io/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.
|
|
|
|
```{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?
|