MyST-Parser icon indicating copy to clipboard operation
MyST-Parser copied to clipboard

Include directive breaks footnote references

Open b-kamphorst opened this issue 1 year ago • 0 comments

What version of myst-parser are you using?

4.0.0

What version dependencies are you using?

Python==3.12.8
docutils==0.21.2
sphinx==8.1.3

Operating system: WSL2 on Windows, Ubuntu distribution.

What operating system are you using?

Linux

Describe the Bug

When parsing a markdown document with footnotes, this parses into a fine HTML. However, if that markdown is included in a .rst file, then the footnotes break. In particular, the references to the footnotes are parsed into <a href="#id1"><span class="problematic" id="id1"> and the footnotes themself get a new id.

See below the rendered output of ./index.html:

Image

It is not clear to me whether this is a bug on MyST's or Sphinx's side.

Expected Behavior

I would expect the footnotes in the HTML that includes Markdown to work properly.

See below the rendered output of ./test.html:

Image

To Reproduce

conf.py

extensions = [
    "myst_parser",
]

index.rst

.. include:: test.md
   :parser: myst_parser.sphinx_

test.md

# Example

Following the footnote example follows [the example in the v4.0.1 documentation](https://myst-parser.readthedocs.io/en/v4.0.1/syntax/typography.html#footnotes), although the manually-numbered footnote is auto-numbered.

- This is a manually-numbered footnote reference.[^a]
- This is an auto-numbered footnote reference.[^myref]

[^myref]: This is an auto-numbered footnote definition.
[^a]: This is a manually-numbered footnote definition.

Then just run sphinx-build . public. The output will show

test.md:5: ERROR: Unknown target name: "a". [docutils]
test.md:6: ERROR: Unknown target name: "myref". [docutils]

Note: the actual example in the documentation has a manually-numbered footnote ^3, but this also introduces an error. This is described in https://github.com/executablebooks/MyST-Parser/issues/1025.

b-kamphorst avatar Feb 13 '25 08:02 b-kamphorst