docs(readme): hyperlink footnote citations to references - #27
Merged
Conversation
Make inline [n] citations link to their specific reference entry via per-item <a id="ref-n"> anchors. Jumps work on GitHub/ReadTheDocs; on PyPI the anchors are stripped by readme_renderer but degrade gracefully to inert, cleanly-rendered [n] link text (same as the existing TOC), so nothing breaks there. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
MyST-Parser parses markdown [n](#ref-n) as a cross-reference and cannot resolve it to the raw-HTML <a id> targets, so sphinx-build -W failed with 7 myst.xref_missing warnings. Write the citation links as raw HTML (<a href="#ref-n">[n]</a>) too: MyST passes raw HTML through verbatim without cross-reference resolution, so no warning is emitted, while GitHub and PyPI render it identically (and this drops the \[ \] escapes). Jumps now resolve in all three renderers on GitHub/Sphinx and degrade to inert links on PyPI. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Makes the inline
[n]footnote citations in the README hyperlink to their specific reference entry, addressing the expectation of scientific users familiar withhyperref.<a id="ref-n"></a>.[\[1\]](#ref-1). The\[ \]escapes preserve the[1]bracket look while avoiding nested-bracket parsing ambiguity.Cross-renderer behavior
readme_rendererstripsidattributes and generates no heading anchors, so the fragment links become inert — but they still render as clean[n]link text with no error. This is the same mechanism the existing Table of Contents already relies on, so no new PyPI risk is introduced.There is no way to make in-page anchor navigation work on PyPI (it strips the anchors); this delivers working jumps on GitHub and graceful, non-breaking degradation on PyPI.
Verify PyPI rendering
🤖 Generated with Claude Code