Contents

References and cross-references

Because jupyter-book is built on top of Sphinx, there are many ways to reference content within your book (or even across other books, or Sphinx websites).

Referencing is accomplished with roles or with markdown link syntax, depending on your use-case. There are a few ways to reference content from your book, depending on what kind of content you’d like to reference.

参见

If you’re getting started, check out Get started with references for more information.

Reference section labels

Labels are a way to add tags to parts of your content so that you can reference them later on. This is helpful if you want to quickly insert links to other parts of your book. Labels can be added before major elements of a page, such as titles or figures.

To add a label, use the following pattern before the element you wish to label:

(my-label)=
# The thing to label

For example, we’ve added the following label above the header for this section with:

(content:references:labels)=
## Cross-references and labels

You can insert cross-references to labels in your content with two kinds of syntax:

  • {ref}`label-text`

  • [](label-text)

For example, the syntax {ref}`content:references:labels` or [](content:references:labels) results in a link to this section like so: Reference section labels.

Reference figures

To reference a figure in your book, first add a figure and ensure that it has both a name as well as a caption associated with it:

source

```{figure} ../images/cool.jpg
:name: my-fig-ref

My figure title.
```

result

../_images/cool.jpg

图 3 My figure title.

Then, reference the figure by its :name: value. For example:

source

result

Here is {ref}`my-fig-ref`

Here is My figure title.

Here is {ref}`My cool fig <my-fig-ref>`

Here is My cool fig

Here is [](my-fig-ref)

Here is My figure title.

Here is [My cool fig](my-fig-ref)

Here is My cool fig

Here is {numref}`my-fig-ref`

Here is 图 3

Here is {numref}`Custom Figure %s text `

Here is Custom Figure 3 text

Reference tables

To reference a table, first create a table and ensure that it has a :name: and a title:

source

```{table} My table title
:name: my-table-ref

| header 1 | header 2 |
|---|---|
| 3 | 4 |
```

result

表 1 My table title

header 1

header 2

3

4

Here are several ways to reference this content:

source

result

Here is {ref}`my-table-ref`

Here is My table title

Here is {ref}`My cool table <my-table-ref>`

Here is My cool table

Here is [](my-table-ref)

Here is My table title

Here is [My cool table](my-table-ref)

Here is My cool table

Here is {numref}`my-table-ref`

Here is 表 1

Here is {numref}`Custom Table %s text `

Here is Custom Table 1 text

Reference content files

To reference other files of book content, use the {doc} role, or link directly to another file with Markdown link syntax. For exmaple:

source

result

Here is {doc}`../file-types/myst-notebooks.md`

Here is Notebooks written entirely in Markdown

Here is {doc}`A different page <../file-types/myst-notebooks.md>`

Here is A different page

Here is [](../file-types/myst-notebooks.md)

Here is Notebooks written entirely in Markdown

Here is [A different page](../file-types/myst-notebooks.md)

Here is A different page

Reference equations

To reference equations, first insert an equation with a label like so:

source

```{math}
:label: my-math-ref
w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}
```

rendered

(1)\[w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}\]

To reference equations, use the {eq} role. It will automatically insert the number of the equation. Note that you cannot modify the text of equation links.

For example:

  • See Equation {eq}`my-math-ref` results in: See Equation (1)

  • See Equation [](my-math-ref) results in: See Equation (1).

Choose the reference text

If you’d like to choose the text of the rendered reference link, use the following pattern:

{someref}`your text here <reference-target>`

Above, reference-target is the reference to which you are referring, and your text here will be the displayed text on the page.

For example, see the following references:

Raw text

Rendered text

{ref}`Here's another references section <content:references:labels>`

Here’s another references section

{doc}`Here's the code outputs section <code-outputs>`

Here’s the code outputs section

Number your references

You can add numbered references to either tables or figures. To add a numbered reference to a table or figure, use the {numref} role. If you wish to use custom text, add %s as a placeholder for the number.

See the examples in each section below for usage.

Check for missing references

You can check for missing references when building a Jupyter Book. To do so, use the following options:

jupyter-book build -W -n --keep-going docs/

This will check for missing references (-n) and turn them into errors (-W), but will still attempt to run the full build (--keep-going), so that you can see all errors in one run.

上一页

Special content blocks

下一页

Control the page layout