Skip to content

docs: MyST renders every in-body relative link as a dead fragment #1132

Description

@nikagra

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

  1. 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.
  2. Sweep the 390 links to …/index.md. Correct on the site; a reader on GitHub gets the raw file
    instead of the rendered directory.
  3. 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

No activity

Activity on this issue will appear here.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions