From 8d9d145135fcf129bd13754aac976cc342daf55f Mon Sep 17 00:00:00 2001 From: cherith <315844584+Cherith1222@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:09:31 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B=20FIX:=20Keep=20project:=20referen?= =?UTF-8?q?ces=20inside=20the=20project?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A missing project: target was resolved through an intersphinx inventory. --- CHANGELOG.md | 10 ++++++ docs/syntax/cross-referencing.md | 2 +- myst_parser/mdit_to_docutils/base.py | 8 ++++- myst_parser/mdit_to_docutils/sphinx_.py | 2 +- myst_parser/mdit_to_docutils/transforms.py | 5 +++ myst_parser/sphinx_ext/myst_refs.py | 6 ++-- .../fixtures/sphinx_link_resolution.md | 2 +- .../sourcedirs/project_scheme/conf.py | 7 ++++ .../sourcedirs/project_scheme/index.md | 17 ++++++++++ .../sourcedirs/project_scheme/objects.inv | 6 ++++ tests/test_sphinx/test_project_scheme.py | 34 +++++++++++++++++++ 11 files changed, 92 insertions(+), 7 deletions(-) create mode 100644 tests/test_sphinx/sourcedirs/project_scheme/conf.py create mode 100644 tests/test_sphinx/sourcedirs/project_scheme/index.md create mode 100644 tests/test_sphinx/sourcedirs/project_scheme/objects.inv create mode 100644 tests/test_sphinx/test_project_scheme.py diff --git a/CHANGELOG.md b/CHANGELOG.md index d79c7010..ff7f3aeb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## Unreleased + +### ‼ï¸� Upgrade notes + +- **`project:` references** (): a `project:` target that is missing from the current project now warns (`myst.xref_missing`) instead of being resolved against an intersphinx inventory. Use `inv:` for an inventory target. A plain `#target` link is unchanged and can still match an inventory. + +### ðŸ�› Bug Fixes + +- ðŸ�› Keep a `project:` reference inside the current project () + ## 5.2.0 - 2026-11-10 Heading anchors are now stable and documented: diff --git a/docs/syntax/cross-referencing.md b/docs/syntax/cross-referencing.md index 4d3d21ff..be10cfc7 100644 --- a/docs/syntax/cross-referencing.md +++ b/docs/syntax/cross-referencing.md @@ -145,7 +145,7 @@ By default, MyST will resolve link destinations according to the following rules 1. Destination beginning with a scheme (e.g. `xxx:`), will be handled according to that scheme: {style=lower-roman} - 1. Destinations beginning with `project:` will be treated as internal references + 1. Destinations beginning with `project:` will be treated as internal references, and are not matched against intersphinx inventories 2. Destinations beginning with `path:` will be treated as downloadable files 3. Destinations beginning with `inv:` will be treated as intersphinx references 4. Autolinks or destinations beginning with `http:`, `https:`, `ftp:`, or `mailto:` will be treated as external [URL] links. diff --git a/myst_parser/mdit_to_docutils/base.py b/myst_parser/mdit_to_docutils/base.py index 7b1808af..f6d13e61 100644 --- a/myst_parser/mdit_to_docutils/base.py +++ b/myst_parser/mdit_to_docutils/base.py @@ -1116,14 +1116,20 @@ def render_link_project(self, token: SyntaxTreeNode) -> None: ) return self.render_link_url(token) - def render_link_anchor(self, token: SyntaxTreeNode, target: str) -> None: + def render_link_anchor( + self, token: SyntaxTreeNode, target: str, *, project_only: bool = False + ) -> None: """Render link token like `[text](#target)`, to a local target. :target: the target id, e.g. `#target` + :project_only: the reference came from the ``project:`` scheme, + so it stays inside this project """ ref_node = nodes.reference() self.add_line_and_source_path(ref_node, token) ref_node["id_link"] = True + if project_only: + ref_node["myst_scope"] = "project" ref_node["refuri"] = self.md.normalizeLinkText(target) self.copy_attributes( token, ref_node, ("class", "id", "reftitle"), aliases={"title": "reftitle"} diff --git a/myst_parser/mdit_to_docutils/sphinx_.py b/myst_parser/mdit_to_docutils/sphinx_.py index 58d3992c..8dce0b72 100644 --- a/myst_parser/mdit_to_docutils/sphinx_.py +++ b/myst_parser/mdit_to_docutils/sphinx_.py @@ -80,7 +80,7 @@ def render_link_project(self, token: SyntaxTreeNode) -> None: destination = cast(str, token.attrGet("href") or "") destination = destination.removeprefix("project:") if destination.startswith("#"): - return self.render_link_anchor(token, destination) + return self.render_link_anchor(token, destination, project_only=True) if not self.sphinx_env.srcdir: # not set in some test situations return self.render_link_url(token) diff --git a/myst_parser/mdit_to_docutils/transforms.py b/myst_parser/mdit_to_docutils/transforms.py index a2e91472..e63dacc3 100644 --- a/myst_parser/mdit_to_docutils/transforms.py +++ b/myst_parser/mdit_to_docutils/transforms.py @@ -285,6 +285,9 @@ def apply(self, **kwargs: t.Any) -> None: target = refnode["refuri"][1:] del refnode["refuri"] + project_only = refnode.get("myst_scope") == "project" + if "myst_scope" in refnode: + del refnode["myst_scope"] # search explicit first if target in explicit: @@ -356,6 +359,8 @@ def apply(self, **kwargs: t.Any) -> None: pending["reflocalid"] = labelid if "reftitle" in refnode: pending["reftitle"] = refnode["reftitle"] + if project_only: + pending["myst_scope"] = "project" inner_node = nodes.inline( "", "", classes=["xref", "myst"] + refnode["classes"] ) diff --git a/myst_parser/sphinx_ext/myst_refs.py b/myst_parser/sphinx_ext/myst_refs.py index ae8980fe..2db8d371 100644 --- a/myst_parser/sphinx_ext/myst_refs.py +++ b/myst_parser/sphinx_ext/myst_refs.py @@ -109,9 +109,9 @@ def run(self, **kwargs: Any) -> None: ) except NoUri: newnode = contnode - if newnode is None: - # If no local domain could resolve the reference, try to - # resolve it as an inter-sphinx reference + if newnode is None and node.get("myst_scope") != "project": + # A plain `#` link may match an intersphinx inventory. + # `project:` is an internal reference; `inv:` is the inventory scheme. newnode = self._resolve_myst_ref_intersphinx( node, contnode, target, search_domains ) diff --git a/tests/test_renderers/fixtures/sphinx_link_resolution.md b/tests/test_renderers/fixtures/sphinx_link_resolution.md index 6cdf66a6..12583583 100644 --- a/tests/test_renderers/fixtures/sphinx_link_resolution.md +++ b/tests/test_renderers/fixtures/sphinx_link_resolution.md @@ -30,7 +30,7 @@ - + diff --git a/tests/test_sphinx/sourcedirs/project_scheme/conf.py b/tests/test_sphinx/sourcedirs/project_scheme/conf.py new file mode 100644 index 00000000..50b087f7 --- /dev/null +++ b/tests/test_sphinx/sourcedirs/project_scheme/conf.py @@ -0,0 +1,7 @@ +extensions = ["myst_parser", "sphinx.ext.intersphinx"] +exclude_patterns = ["_build"] +myst_heading_anchors = 2 + +intersphinx_mapping = { + "inter": ("https://example.com", "objects.inv"), +} diff --git a/tests/test_sphinx/sourcedirs/project_scheme/index.md b/tests/test_sphinx/sourcedirs/project_scheme/index.md new file mode 100644 index 00000000..d6409968 --- /dev/null +++ b/tests/test_sphinx/sourcedirs/project_scheme/index.md @@ -0,0 +1,17 @@ +# Local heading + +[](#local-heading) + + + +[kept](project:#local-heading) + +# Outside the project + + + +[explicit](project:#paragraph-target) + +# Hash still uses the inventory + +[](#paragraph-target) diff --git a/tests/test_sphinx/sourcedirs/project_scheme/objects.inv b/tests/test_sphinx/sourcedirs/project_scheme/objects.inv new file mode 100644 index 00000000..51ef5f81 --- /dev/null +++ b/tests/test_sphinx/sourcedirs/project_scheme/objects.inv @@ -0,0 +1,6 @@ +# Sphinx inventory version 2 +# Project: Example +# Version: 0.0.1 +# The remainder of this file is compressed using zlib. +xÚ…�A +Â0E÷9E@·Ýö.„‚^`L†$�¶¡�¢½½M§ÕÔîŸ÷ÿüŒécðeŠª1}@y”¾6ø<8ªÂŽ5µ—J˜7Û‘)Ü1HuZɲXOJ-êÄÉszŠf�'É›§€b\þ%+j0|áÞœ¡ÛBtŠ µHË®¢6v”¹¦ÎWu­v¹‘5ö\y^‚E1—yx 4v?‹1ªªfT JÙþßí–¤. \ No newline at end of file diff --git a/tests/test_sphinx/test_project_scheme.py b/tests/test_sphinx/test_project_scheme.py new file mode 100644 index 00000000..5675d72b --- /dev/null +++ b/tests/test_sphinx/test_project_scheme.py @@ -0,0 +1,34 @@ +"""`project:` references stay inside the current project.""" + +from __future__ import annotations + +import os +from pathlib import Path + +import pytest + +SOURCE_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "sourcedirs")) +INVENTORY_URL = "https://example.com/index.html#paragraph-target" + + +@pytest.mark.sphinx( + buildername="html", + srcdir=os.path.join(SOURCE_DIR, "project_scheme"), + freshenv=True, + confoverrides={"show_warning_types": True}, +) +def test_project_scheme_does_not_use_intersphinx(app, status, warning): + """A missing `project:` target warns, and a plain `#` link still uses the inventory.""" + app.build() + + assert "build succeeded" in status.getvalue() + warnings = warning.getvalue() + assert warnings.count("target not found: 'paragraph-target'") == 2 + assert "local-heading" not in warnings + assert "[myst.xref_missing]" in warnings + + html = Path(app.outdir, "index.html").read_text(encoding="utf-8") + before, after = html.split("Hash still uses the inventory", maxsplit=1) + assert INVENTORY_URL not in before + assert after.count(INVENTORY_URL) == 1 + assert ">explicitexplicit<" in before