Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Changelog

## Unreleased

### ‼️ Upgrade notes

- **`project:` references** (<gh-issue:1235>): 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 (<gh-issue:1235>)

## 5.2.0 - 2026-11-10

Heading anchors are now stable and documented:
Expand Down
2 changes: 1 addition & 1 deletion docs/syntax/cross-referencing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 7 additions & 1 deletion myst_parser/mdit_to_docutils/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"}
Expand Down
2 changes: 1 addition & 1 deletion myst_parser/mdit_to_docutils/sphinx_.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
5 changes: 5 additions & 0 deletions myst_parser/mdit_to_docutils/transforms.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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"]
)
Expand Down
6 changes: 3 additions & 3 deletions myst_parser/sphinx_ext/myst_refs.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
)
Expand Down
2 changes: 1 addition & 1 deletion tests/test_renderers/fixtures/sphinx_link_resolution.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
<pending_xref refdoc="index" refdomain="True" refexplicit="False" reftarget="test" reftype="myst">
<inline classes="xref myst">

<pending_xref refdoc="index" refdomain="True" refexplicit="False" reftarget="test" reftype="myst">
<pending_xref myst_scope="project" refdoc="index" refdomain="True" refexplicit="False" reftarget="test" reftype="myst">
<inline classes="xref myst">

<pending_xref refdoc="index" refdomain="True" refexplicit="True" reftarget="test" reftype="myst">
Expand Down
7 changes: 7 additions & 0 deletions tests/test_sphinx/sourcedirs/project_scheme/conf.py
Original file line number Diff line number Diff line change
@@ -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"),
}
17 changes: 17 additions & 0 deletions tests/test_sphinx/sourcedirs/project_scheme/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Local heading

[](#local-heading)

<project:#local-heading>

[kept](project:#local-heading)

# Outside the project

<project:#paragraph-target>

[explicit](project:#paragraph-target)

# Hash still uses the inventory

[](#paragraph-target)
6 changes: 6 additions & 0 deletions tests/test_sphinx/sourcedirs/project_scheme/objects.inv
Original file line number Diff line number Diff line change
@@ -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—yx4v?‹1ªªfT JÙþßí–¤.
Expand Down
34 changes: 34 additions & 0 deletions tests/test_sphinx/test_project_scheme.py
Original file line number Diff line number Diff line change
@@ -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 ">explicit</" in before or ">explicit<" in before
Loading