# Navigation Directives URL: /bengal/docs/0.4.3/reference/directives/navigation/ Section: directives Tags: reference, directives, navigation, cards -------------------------------------------------------------------------------- Navigation Directives 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 Use for section index pages - Replace manual card lists with child-cards Add icons in frontmatter - Each child page/section can have icon: name in frontmatter Use weight for ordering - Add weight: 10 to control card sort order (lower = first) Falls back to SVG icons - When no icon is specified, sections get folder icons and pages get file icons Breadcrumbs 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> Related Pages 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 --- Related Layout Directives — Manual cards and tabs Content Organization — How sections and pages work -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 817 - Reading Time: 4 minutes