mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-12 22:25:52 +00:00
151 lines
3.5 KiB
Markdown
151 lines
3.5 KiB
Markdown
In this exercise, you will learn how to create references to other parts of your book, such as chapters, sections, equations, tables, figures, and 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
|
|
|
|
To create a reference to another chapter or section, use 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)
|
|
```
|
|
|
|
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:
|
|
|
|
```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...
|
|
```
|
|
|
|
Then, you can reference this section in three ways:
|
|
|
|
- Using the standard title text:
|
|
```md
|
|
My favourite exercise was {ref}`exercise_1`.
|
|
```
|
|
This will display: My favourite exercise was {ref}`exercise_1`.
|
|
|
|
- Specifying a custom title text:
|
|
```md
|
|
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:
|
|
```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 using `{eq}` and refer to it elsewhere in your text:
|
|
|
|
```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:
|
|
|
|
```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:
|
|
|
|
```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?
|