Navigation Directives

Reference for navigation directives (child-cards, breadcrumbs, siblings, prev-next, related)

5 min read 921 words

Navigation directives automatically generate navigation elements from your site's object tree. They read directly from page and section metadata, eliminating manual content duplication.

Quick Reference

Directive Purpose Reads From
:::{child-cards} Card grid from child pages/sections Section children
:::{breadcrumbs} Hierarchical path navigation Page ancestors
:::{siblings} Links to sibling pages Section pages
:::{prev-next} Sequential navigation Section order
:::{related} Related content by tags Page tags

Key Terms

Object Tree
Bengal's hierarchical representation of your site structure (Site → Sections → Pages). Navigation directives traverse this tree to generate content automatically.
Child Cards
A directive ({child-cards}) that automatically creates a card grid from a section's child pages and subsections.
Breadcrumbs
A directive ({breadcrumbs}) that generates hierarchical navigation showing the current page's location in the site structure.
Siblings
A directive ({siblings}) that lists pages at the same level as the current page within their shared parent section.
Prev/Next
A directive ({prev-next}) that generates previous/next navigation links within a section.
Related
A directive ({related}) that lists pages with matching tags.

Child Cards

Automatically generate a card grid from child sections and pages. This is the recommended approach for section index pages.

Syntax

:::{child-cards}
:columns: 2
:include: sections
:fields: title, description, icon
:::

Options

Option Values Default Description
:columns: 1, 2, 3, 4, auto auto Number of columns in the grid
:include: all, sections, pages all What to include in the cards
:fields: Comma-separated list title, description Metadata fields to display
:gap: small, medium, large medium Gap between cards
:layout: default, horizontal, portrait, compact default Card layout style
:style: default, minimal, bordered default Visual style variant

Available Fields

  • title- Page/section title from frontmatter
  • description- Description from frontmatter
  • icon- Icon from frontmatter (falls back to folder/file SVG icons)

Examples

Example: Basic Child Cards

:::{child-cards}
:columns: 2
:include: sections
:fields: title, description, icon
:::

Example: Include All Children

:::{child-cards}
:columns: 3
:include: all
:fields: title, description
:::

Example: Pages Only

:::{child-cards}
:include: pages
:fields: title, description
:layout: compact
:::

Best Practices

  1. Use for section index pages - Replace manual card lists withchild-cards
  2. Add icons in frontmatter - Each child page/section can haveicon: namein frontmatter
  3. Use weight for ordering - Addweight: 10to control card sort order (lower = first)
  4. Falls back to SVG icons - When no icon is specified, sections get folder icons and pages get file icons

Generate hierarchical breadcrumb navigation showing the page's location in the site.

Syntax

:::{breadcrumbs}
:separator: ›
:show-home: true
:home-text: Home
:home-url: /
:::

Options

Option Default Description
:separator: › Separator character between items
:show-home: true Whether to show home link
:home-text: Home Text for home link
:home-url: / URL for home link

Example Output

<nav class="breadcrumbs" aria-label="Breadcrumb">
  <a class="breadcrumb-item" href="/">Home</a>
  <span class="breadcrumb-separator">›</span>
  <a class="breadcrumb-item" href="/docs/">Docs</a>
  <span class="breadcrumb-separator">›</span>
  <span class="breadcrumb-item breadcrumb-current">Current Page</span>
</nav>

Siblings

List sibling pages (pages in the same section as the current page).

Syntax

:::{siblings}
:limit: 10
:exclude-current: true
:show-description: false
:::

Options

Option Default Description
:limit: 0(no limit) Maximum number of siblings to show
:exclude-current: true Whether to exclude the current page
:show-description: false Whether to show page descriptions

Example Output

<div class="siblings">
  <ul class="siblings-list">
    <li>
      <a href="/docs/theming/assets/">Assets</a>
      <span class="sibling-description">Managing static assets</span>
    </li>
    <li>
      <a href="/docs/theming/themes/">Themes</a>
    </li>
  </ul>
</div>

Prev/Next Navigation

Generate previous/next links for sequential navigation within a section.

Syntax

:::{prev-next}
:show-title: true
:show-section: false
:::

Options

Option Default Description
:show-title: true Show page titles in links
:show-section: false Show section names (reserved for future use)

Example Output

<nav class="prev-next">
  <a class="prev-next-link prev-link" href="/docs/theming/templating/">
    <span class="prev-next-label">← Previous</span>
    <span class="prev-next-title">Templating</span>
  </a>
  <a class="prev-next-link next-link" href="/docs/theming/themes/">
    <span class="prev-next-label">Next →</span>
    <span class="prev-next-title">Themes</span>
  </a>
</nav>

List pages that share tags with the current page.

Syntax

:::{related}
:limit: 5
:title: Related Articles
:show-tags: true
:::

Options

Option Default Description
:limit: 5 Maximum number of related pages to show
:title: Related Articles Section title
:show-tags: false Whether to show matching tags

Example Output

<aside class="related">
  <h3 class="related-title">Related Articles</h3>
  <ul class="related-list">
    <li>
      <a href="/docs/tutorials/theming/">Theming Tutorial</a>
      <span class="related-tags">theming, css, customization</span>
    </li>
    <li>
      <a href="/docs/theming/assets/">Custom CSS Guide</a>
    </li>
  </ul>
</aside>

How It Works

Navigation directives access Bengal's object tree directly:

flowchart LR subgraph "Object Tree" A[Site] --> B[Section] B --> C[Page] B --> D[Subsection] C --> E[metadata] end subgraph "Directives" F[child-cards] -.-> B G[breadcrumbs] -.-> C H[siblings] -.-> B I[prev-next] -.-> C J[related] -.-> E end

This means:

  • No manual updates needed - Cards update automatically when you add/remove pages
  • Single source of truth - Metadata comes from frontmatter, not duplicated in cards
  • Fast lookups - Direct object tree access, no file scanning required

Frontmatter for Navigation

To get the best results, add these fields to your pages' frontmatter:

---
title: My Page
description: A helpful description for cards
icon: book           # Icon name (book, code, rocket, etc.)
weight: 10           # Sort order (lower = first)
tags: [guide, python]  # For related pages
---