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.
1Directive Targets¶
Targets are custom anchors that you can refer to elsewhere, for example, a figure, section, table, program, or proof. To be referenced, they must have a label
/identifier
pair in the AST. These can be created by setting the label
option in many directives. For example, to label and reference a figure, use the following syntax:
2Referencing 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].
MyST Syntax | Rendered |
---|---|
| Section 3 |
| Sec. 3 |
| Sec. 3 |
| Section “Header Targets” |
| bold reference |
| Citations and Bibliography |
| _toc.yml |
Using roles for referencing
It is also possible to use specific roles to reference content, including (ref, numref, eq or doc), depending on your use-case.
These roles are supported to have compatibility with Sphinx. However, it is recommended to use markdown link syntax for referencing content, as it is more portable, is more concise, and has improved features such as inline formatting in the text links.
3Header 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.
How to turn on heading numbering
numbering
By default headings are not numbered, see Section 4 for more information. To turn on numbered headers you need to turn numbering on in the document or project using numbering
in the frontmatter. You can control this for each heading level:
numbering:
heading_1: true
heading_2: true
These will show up, for example, as Section 1
and Section 2.1
. To turn on all heading numbering, use headings: true
.
4Header 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 9 for more details on the numbering object.
5Equations Targets¶
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.
6Notebook 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
:::
See more about reusing Jupyter outputs in figures, adding placeholders, and other options.
7Label 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.
8Referencing using Roles¶
- 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 becomeCustom 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)
.
9Numbering¶
Frontmatter may specify numbering
to customize how various components of the page are numbered. By default, numbering is enabled for figures, equations, tables, and code blocks; it is disabled for headings and other content types contained on the page.
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
headings: true
For components with numbering enabled you may specify start
to begin counting at a number other than 1 and template
to redefine how the component will render when referenced in the text. For this example, the figures on the page will start with Figure 5
and when referenced in the text they will appear as “fig (5)”
numbering:
figure:
start: 5
template: fig (%s)
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).
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"
:::
Finally, 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