Repository navigation
🐛 Keep link titles through cross-reference resolution - #1196
Merged
chrisjsewell merged 7 commits intoNov 9, 2026
Merged
chrisjsewell merged 7 commits into
chrisjsewell merged 7 commits into
Conversation
A CommonMark link title, [text](#target "title"), was dropped whenever the reference was rebuilt: the transform that turns a local anchor into a pending_xref copied ids/names/dupnames but not reftitle, and _process_wrap_node copied "title" instead of aliasing it to "reftitle".
The carry-over in `MystReferenceResolver.run` only copied the authored title when the resolved node had none, so a domain that sets its own `reftitle` (e.g. `py:function` sets the object name) beat what the author wrote. The authored title now always wins, as it already does for intersphinx and for links to documents. The title is also only set on a `nodes.reference`: when the builder has no URI for the target (`NoUri`), the link becomes its bare inline content, which takes no title.
Pin the title through `myst_heading_anchors` (slug and beyond-depth links),
across two documents, from a `{title="..."}` attribute, and into the `<a>`
of the HTML output; and pin that a link without a title gets no `reftitle`.
Pin the title on a link with no `#` and no extension (resolved as an unknown target) and on a reference definition (`[a][r1]`), and check the HTML build of the title test is warning-free.
github-project-automation
Bot
moved this from Todo
to Done
in OSS contributions pipeline
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
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.
[text](#target "title")renders as a tooltip in CommonMark, and the docs say so (docs/syntax/cross-referencing.md: "in HTML titles are rendered as tooltips"). Most links lose it.Checked against markdown-it-py's own
RendererHTMLover the same markdown, one Sphinx build:[a](#index "T")doc root[b](#explicit-target "T")[c](#some-section "T")[d](other.md "T")[e](other.md#anchor "T")[f](https://example.com "T")[g](#nope "T")unresolvedThe reference renderer keeps all 7; MyST kept 2. Two places drop it:
transforms.pyrebuilds the reference as apending_xrefand copiesids,names,dupnames— notreftitle._process_wrap_nodecopiestitlerather than aliasing it toreftitle, which is what every othercopy_attributescall does.Resolution then builds a fresh node, so the carry-over in
myst_refs.pyis needed too — but alone it fixes nothing: the title is already gone by then. With only that one-line change it is still 2 of 7, though it looks like the whole fix.1247 passed, 12 skipped. The 3 failures (test_cmdline[40-linkify],test_extended_syntaxes,test_extended_syntaxes_text) are identical on unpatched master in the same session. ruff 0.15.20 and ruff-format clean.Drafted with Claude Opus 5 (
claude-opus-5); I ran and checked every number above.