template/book/syntax_exercises/009.md

Exercise 9: Referencing using target headers

It can be really useful to refer to a specific section in your book while working in a different file.

::::::{topic} Exercise objective Can you add cross-references to headers? ::::::

1. Navigate to the file you want to work in (for example book/some_content/overview.md) and make sure you're in the correct branch.

2. Identify the section you want to reference and name it between brackets for example exercise_1.

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

3. There are three types of referencing:

• You can use the standard title text which will be the title after the target header

My favourite exercise was {ref}exercise_1.

My favourite exercise was {ref}`exercise_1`.

• You can also specify the title text of the target header (aka specify what the link will say):

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

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

• You can also use Markdown syntax, then the title text is also fully customizable.

My favourite exercise was this one.

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