{{ page.description }}
{% end %} ``` **Returns**: `Page` object or `None` **Use cases**: - Custom link formatting - Accessing page metadata - Conditional rendering ### `anchor(heading, page_path=None)` Link to a heading: ```kida {{ anchor('Installation') }} {{ anchor('Configuration', 'docs/getting-started') }} ``` **Parameters**: - `heading`: Heading text to find (case-insensitive) - `page_path`: Optional page path to restrict search **Returns**: Safe HTML link with anchor fragment **Use cases**: - Table of contents - "Jump to" links - Cross-page heading references ### `relref(path)` Get relative URL without generating a link: ```kida API Docs {% let api_url = relref('docs/api') %} {% if api_url %} {% end %} ``` **Returns**: URL string or empty string if not found **Use cases**: - Custom link HTML - Meta tags - Preload/prefetch links ## Path Resolution Understanding how Bengal resolves paths helps you write reliable links. ### Path Formats Bengal accepts multiple path formats: ```markdown [[docs/getting-started]] # Recommended: path without extension [[docs/getting-started.md]] # Also works: path with extension [[getting-started]] # Slug (if unique across site) [[id:install-guide]] # Custom ID ``` ### Resolution Order When resolving a cross-reference: 1. **Custom ID** (`id:xxx`) — Checked first, fastest lookup 2. **Path lookup** (`docs/page`) — Most explicit, recommended 3. **Slug lookup** (`page-name`) — Fallback, may be ambiguous ### Relative Path Resolution Relative paths resolve from the current page's directory: ```markdown [[./quickstart]] # docs/getting-started/quickstart.md [[../reference/config]] # docs/reference/config.md [[../../_index]] # _index.md (site root) ``` **Rules**: - `.md` extension is optional - `./` refers to current directory - `../` goes up one level - Paths are normalized (trailing slashes, etc.) ## Best Practices ### When to Use Each Method **Use Markdown Links** (`[text](url)`) when: - Linking to external URLs - You need full control over link text - Simple relative paths within a section **Use Cross-References** (`[[path]]`) when: - Linking to internal pages - You want automatic title resolution - You want stable links that survive path changes (with IDs) - You're writing documentation **Use Template Functions** (`ref()`, `doc()`, etc.) when: - Generating links dynamically in templates - Building navigation menus - Creating related pages sections - Conditional link rendering **Use Anchor Links** (`#heading`) when: - Linking to specific sections - Creating table of contents - Cross-referencing specific content **Use Target Directives** (`:::{target}`) when: - Creating anchors not tied to headings - Need stable anchors that survive content restructuring - Migrating from RST/Sphinx (`.. _label:`) - Anchoring before notes/warnings for direct linking **Reference with `[[!target-id]]`**: - Explicit syntax avoids collisions with heading anchors - Makes intent clear (target directive vs heading) - Required for target directive references ### Link Stability **Most Stable** (survives path changes): - Custom IDs: `[[id:my-page]]` - Template functions with IDs: `{{ ref('id:my-page') }}` **Moderately Stable** (survives minor changes): - Path-based cross-references: `[[docs/page]]` - Absolute markdown links: `[text](/docs/page/)` **Least Stable** (breaks on path changes): - Relative markdown links: `[text](../page.md)` - Slug-based references (if slugs change) ### Performance All linking methods use O(1) lookups from pre-built indexes: - Cross-references: Built during discovery phase - Template functions: Use same index - Markdown links: Resolved during rendering **No performance difference** between methods — choose based on use case. ## Examples ### Navigation Menu ```kida ``` ### Related Pages Section ```markdown ## Related Pages - [[docs/tutorials/getting-started|Getting Started]] - [[docs/reference/api|API Reference]] - [[docs/tutorials/examples|Examples]] ``` ### Dynamic Related Pages ```kida {% let related = site.pages | where('tags', page.tags, 'in') | limit(5) %} {% if related %}