Module

rendering.plugins.cross_references

Cross-reference plugin for Mistune.

Provides [[link]] syntax for internal page references with O(1) lookup performance using pre-built xref_index.

View source
1 Class

Classes

CrossReferencePlugin
Mistune plugin for inline cross-references with [[link]] syntax. Syntax: [[docs/installation]]…
7

Mistune plugin for inline cross-references with [[link]] syntax.

Syntax:

[[docs/installation]]           -> Link with page title
[[docs/installation|Install]]   -> Link with custom text
[[#heading-name]]               -> Link to heading anchor
[[id:my-page]]                  -> Link by custom ID
[[id:my-page|Custom]]          -> Link by ID with custom text

Performance: O(1) per reference (dictionary lookup from xref_index) Thread-safe: Read-only access to xref_index built during discovery

Architecture:

  • Runs as inline parser (processes text before rendering)
  • Uses xref_index for O(1) lookups (no linear search)
  • Returns raw HTML that bypasses further processing
  • Broken refs get special markup for debugging/health checks

Note: For Mistune v3, this works by post-processing the rendered HTML to replace [[link]] patterns. This is simpler and more compatible than trying to hook into the inline parser which has a complex API.

Internal Methods 7
__init__
Initialize cross-reference plugin.
1 None 
def __init__(self, xref_index: dict[str, Any])

Initialize cross-reference plugin.

Parameters 1
xref_index dict[str, Any]

Pre-built cross-reference index from site discovery
__call__
Register the plugin with Mistune. For Mistune v3, we post-process the HTML out…
1 None 
def __call__(self, md: Any) -> None

Register the plugin with Mistune.

For Mistune v3, we post-process the HTML output to replace [[link]] patterns. This is simpler and more compatible than hooking into the inline parser.

Parameters 1
md Any
_substitute_xrefs
Substitute [[link]] patterns in HTML, avoiding code blocks.
1 str 
def _substitute_xrefs(self, html: str) -> str

Substitute [[link]] patterns in HTML, avoiding code blocks.

Parameters 1
html str

HTML content that may contain [[link]] patterns
Returns

str —

HTML with [[link]] patterns replaced by links, respecting code blocks

_replace_xrefs_in_text
Substitute [[link]] patterns in text node.
1 str 
def _replace_xrefs_in_text(self, text: str) -> str

Substitute [[link]] patterns in text node.

Parameters 1
text str
Returns

str

_resolve_path
Resolve path reference to link. O(1) dictionary lookup. Supports path#anchor syntax.
2 str 
def _resolve_path(self, path: str, text: str | None = None) -> str

Resolve path reference to link.

O(1) dictionary lookup. Supports path#anchor syntax.

Parameters 2
path str
text str | None
Returns

str

_resolve_id
Resolve ID reference to link. O(1) dictionary lookup.
2 str 
def _resolve_id(self, ref_id: str, text: str | None = None) -> str

Resolve ID reference to link.

O(1) dictionary lookup.

Parameters 2
ref_id str
text str | None
Returns

str

_resolve_heading
Resolve heading anchor reference to link. O(1) dictionary lookup. Resolution …
2 str 
def _resolve_heading(self, anchor: str, text: str | None = None) -> str

Resolve heading anchor reference to link.

O(1) dictionary lookup.

Resolution order:

  1. Check explicit anchor IDs first (by_anchor) - supports {#custom-id} syntax
  2. Fall back to heading text lookup (by_heading) - existing behavior
Parameters 2
anchor str
text str | None
Returns

str