Skip to content

Cross-reference to an explicit target emits a false-positive myst.xref_missing warning #1151

Description

@kdeldycke

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:

  1. [](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
  2. 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"

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions