Found while verifying #1130. The 4.x manual's cross-page links do not survive the MyST parser, and
nothing reports it. This is latent today and lands the moment scylla-4.19.2.x is published.
What happens
Every in-body link written as a bare directory — [configuration](../configuration/), the form used
throughout manual/ — renders under MyST as:
<a class="reference internal" href="#../configuration/"><span class="xref myst">configuration</span></a>
A leading # makes it a fragment on the current page, so the link goes nowhere. On scylla-4.x
today that is 390 links across 84 of the 105 pages; the 20 most common target
../configuration/, ../pooling/, ../metrics/ and ../configuration/reference/.
The build is green and silent: conf.py:117 lists myst.xref_missing in suppress_warnings.
Why it is latent, and why it is about to stop being latent
sphinx_scylladb_markdown picks the parser per version:
current_version = os.environ.get("SPHINX_MULTIVERSION_NAME", "stable")
if current_version in config.scylladb_markdown_recommonmark_versions: ...
All 16 entries in BRANCHES are in scylladb_markdown_recommonmark_versions, so every published
version is built with recommonmark, which renders these links correctly. scylla-4.x is not
published, so its MyST rendering has never reached the site.
scylla-4.19.2.x would be cut from scylla-4.x content, which is MyST-authored ({eval-rst}
toctrees), so it must be built with MyST — and #1056's plan makes it LATEST_VERSION, putting the
390 dead links on /stable/.
Adding it to scylladb_markdown_recommonmark_versions instead is not an escape. Building the same
tree with SPHINX_MULTIVERSION_NAME=scylla-4.19.0.x fails with 575 warnings-as-errors: 12 ×
Pygments lexer name '{eval-rst}' is not known and 97 × document isn't included in any toctree,
because recommonmark cannot parse {eval-rst} and renders every toctree as a code block. The links
themselves are fine there (0 broken, 390 × "External link ... has no URL scheme", warning only).
So the two parsers fail on opposite halves of the same content: recommonmark breaks navigation,
MyST breaks cross-links.
Root cause
make setup stages sources with find . -name README.md -execdir mv '{}' index.md ';'. MyST
resolves a link against that staged tree, so no form is correct both on GitHub and on the site.
Probed on scylla-4.x:
| source form |
MyST output |
correct? |
../configuration/ |
#../configuration/ |
no |
../configuration/README.md |
#../configuration/README.md |
no |
../configuration/index.md |
../configuration/ |
yes |
../configuration/index.md#quick-overview |
../configuration/#quick-overview |
yes |
Options
- Rewrite link targets during
make setup, alongside the rename that causes the mismatch. Keeps
sources correct on GitHub and fixes all 390 in one place.
- Sweep the 390 links to
…/index.md. Correct on the site; a reader on GitHub gets the raw file
instead of the rendered directory.
- Drop
myst.xref_missing from suppress_warnings so the build fails on these. Not a fix, but it
stops the next one landing silently — and would fail the build today, so it has to follow 1 or 2.
Worth deciding before scylla-4.19.2.x is cut, since that publish is what makes this visible.
Refs: #1056, #1130
Found while verifying #1130. The 4.x manual's cross-page links do not survive the MyST parser, and
nothing reports it. This is latent today and lands the moment
scylla-4.19.2.xis published.What happens
Every in-body link written as a bare directory —
[configuration](../configuration/), the form usedthroughout
manual/— renders under MyST as:A leading
#makes it a fragment on the current page, so the link goes nowhere. Onscylla-4.xtoday that is 390 links across 84 of the 105 pages; the 20 most common target
../configuration/,../pooling/,../metrics/and../configuration/reference/.The build is green and silent:
conf.py:117listsmyst.xref_missinginsuppress_warnings.Why it is latent, and why it is about to stop being latent
sphinx_scylladb_markdownpicks the parser per version:All 16 entries in
BRANCHESare inscylladb_markdown_recommonmark_versions, so every publishedversion is built with recommonmark, which renders these links correctly.
scylla-4.xis notpublished, so its MyST rendering has never reached the site.
scylla-4.19.2.xwould be cut fromscylla-4.xcontent, which is MyST-authored ({eval-rst}toctrees), so it must be built with MyST — and #1056's plan makes it
LATEST_VERSION, putting the390 dead links on
/stable/.Adding it to
scylladb_markdown_recommonmark_versionsinstead is not an escape. Building the sametree with
SPHINX_MULTIVERSION_NAME=scylla-4.19.0.xfails with 575 warnings-as-errors: 12 ×Pygments lexer name '{eval-rst}' is not knownand 97 ×document isn't included in any toctree,because recommonmark cannot parse
{eval-rst}and renders every toctree as a code block. The linksthemselves are fine there (0 broken, 390 × "External link ... has no URL scheme", warning only).
So the two parsers fail on opposite halves of the same content: recommonmark breaks navigation,
MyST breaks cross-links.
Root cause
make setupstages sources withfind . -name README.md -execdir mv '{}' index.md ';'. MySTresolves a link against that staged tree, so no form is correct both on GitHub and on the site.
Probed on
scylla-4.x:../configuration/#../configuration/../configuration/README.md#../configuration/README.md../configuration/index.md../configuration/../configuration/index.md#quick-overview../configuration/#quick-overviewOptions
make setup, alongside the rename that causes the mismatch. Keepssources correct on GitHub and fixes all 390 in one place.
…/index.md. Correct on the site; a reader on GitHub gets the raw fileinstead of the rendered directory.
myst.xref_missingfromsuppress_warningsso the build fails on these. Not a fix, but itstops the next one landing silently — and would fail the build today, so it has to follow 1 or 2.
Worth deciding before
scylla-4.19.2.xis cut, since that publish is what makes this visible.Refs: #1056, #1130