WARNING: 'myst' cross-reference target not found: 'level-4-header-title' [myst.xref_missing]

executablebooks / MyST-Parser

An extended commonmark compliant parser, with bridges to docutils/sphinx

https://myst-parser.readthedocs.io

MIT License

759 stars 196 forks source link

WARNING: 'myst' cross-reference target not found: 'level-4-header-title' [myst.xref_missing] #885

Open syspect-sec opened 8 months ago

syspect-sec commented 8 months ago

What version of `myst-parser` are you using?

2.0.0

What version dependencies are you using?

Name: Sphinx Version: 7.2.6

Name: docutils Version: 0.20.1

What operating system are you using?

Mac

Describe the Bug

When internal linking to a fourth level header (#### Fourth Level Header) using the syntax [link text](#fourth-level-header), upon doc compilation myst throws this error the first time during compilation: WARNING: 'myst' cross-reference target not found: 'fourth-level-header' [myst.xref_missing]. However the link works when inspecting and testing the compiled docs.

Expected Behavior

An error will not be thrown.

To Reproduce

Try to compile this file below with a command such as sphinx-build -b html src build:

# First

[link to first](#first)

## Second

[link to second](#second)

### Third

[link to third](#third)

#### Fourth

[link to fourth](#fourth)

results in error:

WARNING: 'myst' cross-reference target not found: 'fourth' [myst.xref_missing]

welcome[bot] commented 8 months ago

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

aeisenbarth commented 8 months ago

I get the same, not specifically for 4-level headers, but also 2-level headers.

Note: A warning != error. What is happening here does not break any functionality.

I suspect this is the case for all implicit targets. Possibly they are not resolved during Sphinx build time but only in the generated HTML.

Since implicit targets are documented as a feature, I would expect a warning only if I used something incorrectly. If these warnings are inherent to implicit targets, it would be nice to mention this in the documentation (below the "discouraged" block).
I try to care about and resolve warnings so that I don't oversee a new and important one. For that, it is important not to get flooded with irrelevant warnings. It would be great there is something that can be done to avoid emitting this warning at build time.

sumezulike commented 7 months ago

Increasing the myst_heading_anchors variable to the deepest level could get rid of the warnings, it's currently 0 by default. See MyST Configuration

aeisenbarth commented 7 months ago

Oh, thanks! That solves it perfectly.