Skip To Article

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.

Directive Targets and Cross References

Targets are custom anchors that you can refer to elsewhere, for example, a figure, section, table, program, or proof. To be referenceable, they must have a label/identifier pair in the AST. These can be setup by setting the label or name option in a directive.

Cross-referencing content is accomplished with markdown link syntax ([text](#link)) or through specific roles (ref, numref, eq or doc), depending on your use-case.

Specification

In-line reference to an associated node

type: string, (“crossReference”)
See also Node
kind: string, optional, (“eq” | “numref” | “ref”)
Indicates if the references should be numbered.
children: array, optional, (StaticPhrasingContent)
Children of the crossReference, can include text with “%s” or “{number}” and enumerated references will be filled in.
identifier: string
See also OptionalAssociation
label: string, optional
See also OptionalAssociation
position: object, optional, (Position)
See also Node
data: object, optional
See also Node

Example

Markup
AST
Render
see {numref}`my-table`

```{list-table}  Caption text
:name: my-table

*   - Head 1
*   - Row 1
```

Using markdown link syntax is one of the most versatile ways to link to content. This uses the standard CommonMark syntax for a link ([text](#link)), and the link can either be a label or a link to a document. For example:

MyST SyntaxRendered
[A **bolded _reference_** to a page](./references.md)
[A reference to a header](#targeting-headers)
A bolded reference to a page
A reference to a header

Using the {ref} role

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:

{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>`

Numbering references with {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. You can try this in the demo above!

Using the {eq} role

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.

Using the {doc} role

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

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

```{math}
:label: my-math-label
e=mc^2
```

See Equation {eq}`my-math-label`!

Target Node

Placing a Target node allows you to cross reference the subsequent node by target value.

Specification

Target node - provides identifier/label for the following node

type: string, (“mystTarget”)
See also Node
label: string, optional
unresolved target label
position: object, optional, (Position)
See also Node
data: object, optional
See also Node

Example

Markup
AST
Render
(my_ID)=
# My Header

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

MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication, part of Jupyter.