smhk

Sphinx: Cross-referencing with MyST Markdown

In Sphinx, using the MyST extension enables using Markdown (instead of ReStructuredText). To create a cross-reference, first you must enable auto-generated header anchors by adding this line to your conf.py:1

conf.py
myst_heading_anchors = 3

you can then use this syntax:

page_1.md
# Page 1

This is [a cross-reference to "My section" on page 2](./page_2.md#my-section).
page_2.md
# Page 2

## My section

Hello, world!

Clicking the link on page_1.md will then take you to “My section” on page_2.md.

Troubleshooting §

myst.xref_missing §

If you get an error such as the following:

C:\path\to\project\source\page_1.md:3: WARNING: local id not found in doc 'page_2': 'my-section' [myst.xref_missing]

This is likely because you need to set myst_heading_anchors in your conf.py2. By default, MyST does not generate heading anchors, and so is unable to create the cross-reference unless if you explicitly enable this setting.

  1. The number 3 is how many headings deep MyST should generate anchors. If you are cross-referencing a ##### level 5 heading you would need to set this to 5. ↩︎

  2. At first, I tried to solve this by creating explicit targets. This appeared to work, but it turns out the WARNING only shows the first time you run sphinx-build if you make no changes to the file, so it was masking the fact that the underlying issue was still present. Using myst_heading_anchors is also much nicer because the anchors are generated automatically. ↩︎