Module

roles.builtins.reference

Reference roles for cross-linking.

Provides roles for linking to other parts of the documentation:

  • ref: Reference to a labeled target
  • doc: Reference to another document

Example:

See installation-guide for setup. Read the /getting-started guide.

2Classes

Classes

RefRole 4 ▼
Handler for {ref}`target` role. Creates a cross-reference to a labeled target. The target is resol…

Handler for target role.

Creates a cross-reference to a labeled target. The target is resolved during rendering based on the document structure.

Syntax:

{ref}`target` - Uses target as both ID and display text
{ref}`display text <target>` - Custom display text

Thread Safety:

Stateless handler. Safe for concurrent use.

Attributes

Name Type Description
names ClassVar[tuple[str, ...]] —
token_type ClassVar[str] —

Methods

parse 3 Role ▼
Parse ref role content. Handles both `target` and `text ` syntaxes.
def parse(self, name: str, content: str, location: SourceLocation) -> Role
Parameters
Name Type Description
name —
content —
location —
Returns
Role
render 2 ▼
Render ref as a link placeholder. Actual link resolution happens at a higher l…
def render(self, node: Role, sb: StringBuilder) -> None

Render ref as a link placeholder.

Actual link resolution happens at a higher level (Bengal). Here we output a marker that can be resolved later.

Parameters
Name Type Description
node —
sb —
DocRole 4 ▼
Handler for {doc}`path` role. Creates a link to another document. The path is resolved relative to…

Handler for path role.

Creates a link to another document. The path is resolved relative to the current document.

Syntax:

{doc}`/path/to/doc` - Link to document
{doc}`display text </path/to/doc>` - Custom display text

Thread Safety:

Stateless handler. Safe for concurrent use.

Attributes

Name Type Description
names ClassVar[tuple[str, ...]] —
token_type ClassVar[str] —

Methods

parse 3 Role ▼
Parse doc role content.
def parse(self, name: str, content: str, location: SourceLocation) -> Role
Parameters
Name Type Description
name —
content —
location —
Returns
Role
render 2 ▼
Render doc reference as a link placeholder.
def render(self, node: Role, sb: StringBuilder) -> None
Parameters
Name Type Description
node —
sb —