Footnotes in the self-care chapter are throwing build warnings:
WARNING: 'myst' cross-reference target not found: 'user-content-fn-1' [myst.xref_missing]
Root cause: The source uses [^1] footnote syntax, which MyST renders with user-content-fn-* IDs (a GitBook convention that MyST's markdown-it parser preserves). However, Sphinx's cross-reference resolver does not register these IDs as valid targets, so it reports them as missing.
The footnotes render correctly in the HTML output — the references and back-references work. The warnings are false positives from MyST's cross-reference validation, but they clutter the build log and may mask real issues.
Fix (options):
- Add
user-content-fn-* patterns to myst_xref_missing suppression in conf.py:
myst_xref_missing_suppress = [r"user-content-fn-\d+"]
- Configure MyST to use Sphinx-native footnote IDs instead of GitBook-style IDs
- Suppress the specific warning type in
conf.py:
suppress_warnings = ["myst.xref_missing"]
(Reported by @sanchuanhehe in theopensourceway/production#6)
Footnotes in the self-care chapter are throwing build warnings:
Root cause: The source uses
[^1]footnote syntax, which MyST renders withuser-content-fn-*IDs (a GitBook convention that MyST's markdown-it parser preserves). However, Sphinx's cross-reference resolver does not register these IDs as valid targets, so it reports them as missing.The footnotes render correctly in the HTML output — the references and back-references work. The warnings are false positives from MyST's cross-reference validation, but they clutter the build log and may mask real issues.
Fix (options):
user-content-fn-*patterns tomyst_xref_missingsuppression inconf.py:conf.py:(Reported by @sanchuanhehe in theopensourceway/production#6)