Module

rendering.template_functions.crossref

Cross-reference functions for templates.

Provides 4 functions for cross-referencing pages and headings with O(1) performance.

View source
5 Functions

Functions

register
Register cross-reference functions with Jinja2 environment.
2 None 
def register(env: Environment, site: Site) -> None

Register cross-reference functions with Jinja2 environment.

Parameters 2

Name Type Default Description
env Environment —
site Site —
ref
Generate cross-reference link to a page or heading. O(1) lookup - zero performance impact!
4 Markup 
def ref(path: str, index: dict[str, Any], baseurl: str = '', text: str | None = None) -> Markup

Generate cross-reference link to a page or heading.

O(1) lookup - zero performance impact!

Parameters 4

Name Type Default Description
path str —

Path to reference ('docs/installation', 'id:my-page', or slug)
index dict[str, Any] —

Cross-reference index from site
baseurl str ''
text str | None None

Optional custom link text (defaults to page title)

Returns

Markup —

Safe HTML link or broken reference indicator

doc
Get page object by path. O(1) lookup - zero performance impact! Useful for accessing page metadata…
2 Page | None 
def doc(path: str, index: dict[str, Any]) -> Page | None

Get page object by path.

O(1) lookup - zero performance impact! Useful for accessing page metadata in templates.

Parameters 2

Name Type Default Description
path str —

Path to page ('docs/installation', 'id:my-page', or slug)
index dict[str, Any] —

Cross-reference index from site

Returns

Page | None —

Page object or None if not found

anchor
Link to a heading (anchor) in a page.
4 Markup 
def anchor(heading: str, index: dict[str, Any], baseurl: str = '', page_path: str | None = None) -> Markup

Link to a heading (anchor) in a page.

Parameters 4

Name Type Default Description
heading str —

Heading text to link to
index dict[str, Any] —

Cross-reference index from site
baseurl str ''
page_path str | None None

Optional page path to restrict search (default: search all)

Returns

Markup —

Safe HTML link to heading or broken reference indicator

relref
Get relative URL for a page. Returns just the URL without generating a full link. Useful for custo…
3 str 
def relref(path: str, index: dict[str, Any], baseurl: str = '') -> str

Get relative URL for a page.

Returns just the URL without generating a full link. Useful for custom link generation.

Parameters 3

Name Type Default Description
path str —

Path to page
index dict[str, Any] —

Cross-reference index from site
baseurl str ''

Returns

str —

URL string or empty string if not found