# reference URL: /patitas/api/roles/builtins/reference/ Section: builtins Description: 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 \{ref}`installation-guide` for setup. Read the \{doc}`/getting-started` guide. --- > For a complete page index, fetch /patitas/llms.txt. Open LLM text (/patitas/api/roles/builtins/reference/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Froles%2Fbuiltins%2Freference%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Froles%2Fbuiltins%2Freference%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Froles%2Fbuiltins%2Freference%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Froles%2Fbuiltins%2Freference%2Findex.txt) 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 {ref}`installation-guide`for setup. Read the {doc}`/getting-started`guide. 2Classes ## Classes `RefRole` 4 ▼ Handler for \{ref}`target` role. Creates a cross-reference to a labeled target. The target is reso… Handler for {ref}`target` (/patitas/api/nodes/#Role) 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 ` - 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 (/patitas/api/nodes/#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 (/patitas/api/nodes/#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 t… Handler for {doc}`path` (/patitas/api/differ/#ASTChange) 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 ` - 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 (/patitas/api/nodes/#Role)` ▼ Parse doc role content. `def parse(self, name: str, content: str, location: SourceLocation) -> Role` ##### Parameters Name Type Description `name` `—` `content` `—` `location` `—` ##### Returns `Role (/patitas/api/nodes/#Role)` `render` 2 ▼ Render doc reference as a link placeholder. `def render(self, node: Role, sb: StringBuilder) -> None` ##### Parameters Name Type Description `node` `—` `sb` `—`