Cross-references#

MyST-Parser offers powerful cross-referencing features, to link to URLs, documents, headers, figures and more, that are portable across output formats and generate warnings when broken.

This page covers the basics of setting up referenceable targets for content and how to reference them.

1.  Creating explicit targets#

Targets are used to define custom anchors that you can refer to elsewhere in your documentation.

There are three primary ways to create targets:

  1. Annotating a syntax block with (target)=

  2. Annotating a syntax bloc/inline/span with an {#id} attribute (using the attrs_block and attrs_inline extensions)

  3. Adding a name option to a directive

(heading-target)=
### Heading

{#paragraph-target}
This is a paragraph, with an `id` attribute.

This is a [span with an `id` attribute]{#span-target}.

:::{note}
:name: directive-target

This is a directive with a `name` option
:::

[reference1](#heading-target), [reference2](#paragraph-target),
[reference3](#span-target), [reference4](#directive-target)

Heading

This is a paragraph, with an id attribute.

This is a span with an id attribute.

Note

This is a directive with a name option

reference1, reference2, reference3, reference4

There are also other ways to create targets, specific to certain directives, such as glossaries create targets for terms, and code APIs create targets for objects:

{.glossary}
my other term
: Definition of the term

[Link to a term](<#my other term>)

```{py:class} mypackage.MyClass
:nocontentsentry:
Docstring content
```

[Link to a class](#mypackage.MyClass)
my other term

Definition of the term

Link to a term

class mypackage.MyClass#

Docstring content

Link to a class

See also

The footnotes section, covers how to create and link to footnotes, and the sphinxcontrib.bibtex extension provides a means to reference bibliographies.

2.  Implicit targets#

Whole documents can be referenced by path. Headings within documents can also be assigned an implicit target, by setting the myst_heading_anchors configuration option. This is should be set to an integer, between 1 and 6, indicating the depth of headings to assign targets to.

The anchor “slugs” are created according to the GitHub implementation: heading titles are lower cased, punctuation is removed, spaces are replaced with -, and uniqueness is enforced by suffix enumeration.

For example, using myst_heading_anchors = 2:

## A heading with slug

## A heading with slug

<project:#a-heading-with-slug>

[Explicit title](#a-heading-with-slug-1)

A heading with slug

A heading with slug

A heading with slug

Explicit title

For more information see the auto-generated header anchors section.

Warning

In general, it is discouraged to rely on implicit targets, since they are easy to break, if for example a document/heading is moved or renamed.

4.  Reference roles#

Sphinx offers numerous roles for referencing specific objects.

These can also within MyST documents, although it is recommended to use the Markdown syntax where possible, which is more portable and native to MyST.

- {ref}`syntax/referencing`, {ref}`Explicit text <syntax/referencing>`
- {term}`my other term`
- {doc}`../intro`, {doc}`Explicit text <../intro>`
- {download}`example.txt`, {download}`Explicit text <example.txt>`
- {py:class}`mypackage.MyClass`, {py:class}`Explicit text <mypackage.MyClass>`
- {external:class}`sphinx.application.Sphinx`, {external:class}`Explicit text <sphinx.application.Sphinx>`
- {external+sphinx:ref}`code-examples`, {external+sphinx:ref}`Explicit text <code-examples>`

---

- <project:#syntax/referencing>, [][syntax], [Explicit text][syntax]
- [](<#my other term>)
- <project:../intro.md>, [Explicit text](../intro.md)
- <path:example.txt>, [Explicit text](example.txt)
- <project:#mypackage.MyClass>, [Explicit text](#mypackage.MyClass)
- <inv:#*Sphinx>, [Explicit text](#sphinx.application.Sphinx)
- <inv:sphinx#code-examples>, [Explicit text](inv:sphinx#code-examples)

[syntax]: #syntax/referencing

5.  Handling invalid references#

When building your documentation, it is recommended to run in nitpicky mode, which will emit warnings for any invalid references.

you may encounter warnings such as:

intro.md:1: WARNING: 'myst' cross-reference target not found: 'reference' [myst.xref_missing]

intro.md:2: WARNING: Multiple matches found for 'duplicate': inter:py:module:duplicate, inter:std:label:duplicate [myst.iref_ambiguous]

To fully suppress a specific warning type, you can use the suppress_warnings configuration option, in Sphinx’s conf.py file:

suppress_warnings = ["myst.xref_missing", "myst.iref_ambiguous"]

or in docutils.conf or command-line tool:

[general]
myst-suppress-warnings = myst.xref_missing, myst.iref_ambiguous

In Sphinx specific reference warnings can also be suppressed, using the nitpick_ignore and nitpick_ignore_regex configuration options.

nitpick_ignore = [("myst", "reference")]

To handle ambiguous references, for intersphinx references see the Cross-project (intersphinx) links section, or the domains searched for all Markdown references can be restricted globally or per-document using the myst_ref_domains configuration.

myst_ref_domains = ["std", "py"]