What version of myst-parser are you using?
5.1.0
What version dependencies are you using?
- sphinx 9.1.0
- docutils 0.22.4
- Python 3.14.3
What operating system are you using?
Mac
Describe the Bug
A path-based Markdown link to an explicit target in another document, like [text](other.md#target), emit WARNING: local id not found in doc 'other': 'target' [myst.xref_missing], even though MyST renders the correct, working href for it (other.html#target, which is a real ID in the output).
The pathless form of the same reference, [text](#target), resolves silently and renders the identical href. So the warning fires only on the path-based spelling, on a link that is not actually broken.
It looks like explicit (target)= / {#id} anchors are treated as global and meant to be referenced pathless, while path-based [](file.md#frag) resolves only against the target document's heading-derived anchors. If that split is by design, then the bug is narrower: myst.xref_missing should not be emitted for a path-based reference who's rendered href points at a valid ID in the target document.
Expected Behavior
Either:
[](other.md#target) resolves against explicit targets defined in other.md (consistent with same-document [](#target) resolution, and with the working href MyST already emits), or
- if path-based references are intentionally scoped to heading anchors only, no
myst.xref_missing warning is emitted for a link whose rendered href is valid.
To Reproduce
conf.py:
extensions = ["myst_parser"]
myst_enable_extensions = ["attrs_block"]
myst_heading_anchors = 3
index.md:
# Index
```{toctree}
a
b
```
a.md:
# Doc A
(custom-anchor)=
## My Heading
Some content.
b.md:
# Doc B
- [path-based reference](a.md#custom-anchor)
- [pathless reference](#custom-anchor)
Build:
$ sphinx-build -b html . _build
.../b.md:3: WARNING: local id not found in doc 'a': 'custom-anchor' [myst.xref_missing]
Only line 3 (the path-based reference) warns; line 4 (pathless) is silent.
Both links are identical and correct in the output, and the target id exists:
$ grep -o 'href="a.html#custom-anchor"' _build/b.html
href="a.html#custom-anchor"
href="a.html#custom-anchor"
$ grep -o 'id="custom-anchor"' _build/a.html
id="custom-anchor"
What version of
myst-parserare you using?5.1.0
What version dependencies are you using?
What operating system are you using?
Mac
Describe the Bug
A path-based Markdown link to an explicit target in another document, like
[text](other.md#target), emitWARNING: local id not found in doc 'other': 'target' [myst.xref_missing], even though MyST renders the correct, working href for it (other.html#target, which is a real ID in the output).The pathless form of the same reference,
[text](#target), resolves silently and renders the identical href. So the warning fires only on the path-based spelling, on a link that is not actually broken.It looks like explicit
(target)=/{#id}anchors are treated as global and meant to be referenced pathless, while path-based[](file.md#frag)resolves only against the target document's heading-derived anchors. If that split is by design, then the bug is narrower:myst.xref_missingshould not be emitted for a path-based reference who's rendered href points at a valid ID in the target document.Expected Behavior
Either:
[](other.md#target)resolves against explicit targets defined inother.md(consistent with same-document[](#target)resolution, and with the working href MyST already emits), ormyst.xref_missingwarning is emitted for a link whose rendered href is valid.To Reproduce
conf.py:index.md:a.md:b.md:Build:
Only line 3 (the path-based reference) warns; line 4 (pathless) is silent.
Both links are identical and correct in the output, and the target id exists: