Cross-references

References refer to labeled content (e.g. a figure, document or table) and automatically generates links and extra information, like numbering. This page covers the basics of setting up references to content and shows examples for sections, figures, tables and equations.

1Reference syntax¶

There are several ways that you can define cross-references with MyST. Below are the major ones.

1.1Reference using Links¶

Cross-referencing content is accomplished with markdown link syntax ([text](#target)) where #target is the target label^[1], like the figure, equation or section header that you are referencing. If you leave the text empty, MyST will fill in the link with the title, caption, document name, or equation number as appropriate (e.g. “Figure 1” or “Section 1.3.7”). If you do supply text, you can control what is displayed in the reference, as well as have access to placing the name and enumerator of the target, using {name} and {number}, respectively^[2].

1.2Reference using a shorthand @ syntax¶

You can reference targets with a short-hand using the @ symbol, like so:

@target

This cuts down on the amount of markdown that is needed to create the reference. For example, the following text:

Other ways to reference are @link-references and the @ref-role role.

Results in:

Other ways to reference are Section 1.1 and the ref role.

1.3Reference using MyST roles¶

Roles are a more explicit way of defining references that provide more configuration at the cost of requiring more complexity to write. There several roles that define various kinds of references in MyST. In many cases, the short-hand syntax described above are aliases for these roles. Below we describe the most commonly-used ones.

ref

The {ref} role can be used to bring the title or caption directly in line, the role can take a single argument which is the label, for example, {ref}`reference-target`

You can also choose the reference text directly (not taking from the title or caption) by using, {ref}`your text here <reference-target>`.

numref

The {numref} role is exactly the same as the above {ref} role, but also allows you to use a %s in place of the number, which will get filled in when the content is rendered. For example, {numref}`Custom Table %s text <my-table-ref>`. will become Custom Table 3 text.

eq

The {eq}`my-equation` syntax creates a numbered link to the equation, which is equivalent to [](#my-equation) as there is no text content to fill in a title or caption.

doc

The {doc}`./my-file.md` syntax creates a link to the document, which is equivalent to [](./my-file.md).

download

The {download}`./my-file.zip` syntax creates a download to a document, which is equivalent to [](./my-file.zip).

2Targets and labels for referencing¶

The content you wish to reference is called a target, and to be targeted that content must have a label. For example, in this reference syntax:

[](#my-targets-label)

The text my-targets-label is the label for the target. There are many ways that you can label a target, and the sections below describe the most common approaches.

2.1Directive Targets¶

Labels can be given to most directives by setting the label option. For example, to label and reference a figure, use the following syntax:

Or, to label an equation:

2.2Header Targets¶

To add labels to a header use (my-section)= before the header, these can then be used in markdown links and {ref} roles. This is helpful if you want to quickly insert links to other parts of your book. Referencing a heading will show the heading and the subsequent two pieces of content^[3], unless a header is encountered.

numbering:
  heading_1: true
  heading_2: true

2.2.1Header Numbering¶

By default section numbering for headers is turned off with numbering for figure and table numbering enabled. To turn on numbering for headers, you can can change the frontmatter in the document or project. See Section 3 for more details on the numbering object.

2.3Notebook Cell Targets¶

You can label notebook cells using a comment at the top of the cell, using a #| label: syntax, or have this added directly in the notebook metadata for the cell.

#| label: my-cell
print('hello world')

The cell output or the entire cell can be embedded or referred to using the image or link syntax.

[](#my-cell) - This is a cross-reference to a notebook cell
![](#my-cell) - This will embed the output of a notebook cell

or as a figure directive, where you can then add a caption. If you are referring to that figure in a further cross reference that figure (i.e. not the original cell), give it a new name.

:::{figure} #my-cell
:label: fig-my-cell
:::

2.4Label Anything¶

It is possible to label any document node by adding (my-label)= before any other block of content. These can be referenced using the {ref} role, but by default will not be enumerated, so you cannot use %s or {number} in the content.

3Numbering¶

Frontmatter may specify numbering to customize how various components of the page are numbered. By default, numbering is enabled for figures, equations, tables, math, and code blocks; it is disabled for headings and other content types contained on the page. Additionally, by default, numbering resets on every page.

3.1Enabling and Disabling Numbering¶

To enable numbering of all content, you may simply use:

numbering: true

Similarly, to disable all numbering:

numbering: false

The numbering object allows you to be much more granular with enabling and disabling specific components:

numbering:
  code: false
  math: false
  headings: true

Numbering may be used for figure as above, as well as subfigure, equation, subequation, table, code, headings (for all heading depths), and heading_1 through heading_6 (for modifying each depth separately).

3.2Numbering Custom Content¶

You may also add numbering for custom content kinds:

---
numbering:
  box:
    enabled: true
---

:::{figure} image.png
:label: my-box
:kind: box

This figure will be numbered as "Box 1"
:::

3.3Customizing Numbering Appearance¶

By default, all components are numbered sequentially as 1, 2, 3... However, under the numbering object, you may specify enumerator. For now, this applies to all numberings on the page. Instead of enumerating as simply 1, 2, 3... they will follow the template set in enumerator. For example, in Appendix 1, you may want to use the following numbering so content is enumerated as A1.1, A1.2, A1.3...

numbering:
  enumerator: A1.%s

If you want to control the numbering for a specific figure, you can use the {figure.enumerator} option. This will give the figure a specific enumerator, and will not increment the counting for other figures. This is helpful if you want to explicitly count figure 2a and then carry on counting figures as normal; alternatively you can take control of numbering entirely by setting {figure.enumerator} on every figure.

You may also redefine how the component will render when referenced in the text by specifying template. For this example, the figures on the page will start with Figure 1 and when referenced in the text they will appear as “fig (1)”

numbering:
  figure:
    template: fig (%s)

3.4Continuous Numbering¶

By default, numbering will reset on every page. However, you may enable continuous numbering across all pages by specifying continue: true in your numbering object. If this is specified on a single page, it will continue counting from the previous page; if specified in your myst.yml, counting will be continuous across the entire project.

numbering:
  figure:
    continue: true

You may also override the start value to begin counting on the page at a specific number. This is useful, for example, if you want continuous figure numbering across your project until you reach your appendix, then you want to reset to A1:

numbering:
  enumerator: A%s
  figure:
    start: 1

3.5Title Numbering¶

By default, page titles are not numbered, even if you turn on all numbering with numbering: true. However, you may add title to your numbering object:

numbering:
  title: true

Doing so will enumerate all the titles in your MyST project. These numberings will follow the structure of your table of contents. So, given the structure:

toc:
  - file: index.md
  - file: section_a.md
    children:
      - file: chapter_1.md
      - file: chapter_2.md
  - file: section_b.md

The numbering will be: 1 - index.md, 2 - section_a.md, 2.1 - chapter_1.md, 2.2 - chapter_2.md, and 3 - section_b.md.

If both title and heading numbering are enabled, these will be incremented together. So, for the example above, if there is a single heading of level 1 in section_a.md, it will increment the same count as the title of chapter_1.md and chapter_2.md (i.e. the heading will be 2.1 and the chapters will be 2.2 and 2.3):

numbering:
  title: true
  headings: true

You can further customize this behavior by setting an explicit offset value on a page. By default the offset matches the nesting level in the table of contents, but, for example, if you want page numbering to be flat, despite nesting in the table of contents, you can set offset: 0:

numbering:
  title:
    enabled: true
    offset: 0

For the example above, the numbering will change to: 1 - index.md, 2 - section_a.md, 3 - chapter_1.md, 4 - chapter_2.md, and 5 - section_b.md.