# Layout Directives URL: /bengal/docs/0.5.0/reference/directives/layout/ Section: directives Tags: reference, directives, layout, cards, tabs -------------------------------------------------------------------------------- Layout Directives Layout directives organize content into structured components like card grids, tabs, and collapsible sections. Key Terms Card Grid A container directive ({cards}) that creates a responsive grid of card components. Supports flexible column layouts and responsive breakpoints. Card An individual card component ({card}) within a card grid. Can include icons, links, images, colors, and footer content. Tab Set A container directive ({tab-set}) that groups multiple tab items together. Provides tabbed navigation for organizing related content. Tab Item An individual tab ({tab-item}) within a tab set. Contains content for one tab panel. Dropdown A collapsible section directive ({dropdown}) that can be expanded or collapsed. Useful for optional or advanced content to reduce cognitive load. Grid A Sphinx-Design compatibility directive ({grid}) that converts to card grids internally. Prefer {cards} for new content. Cards Create responsive card grids for navigation, feature highlights, or content organization. Card Grid ({cards}) Container for multiple cards with responsive column layout. Use :::{/cards} to close. Syntax: :::{cards} :columns: 3 :gap: medium :style: default :variant: navigation :::{card} Card Title :icon: book :link: docs/getting-started :color: blue :image: /hero.jpg :footer: Updated 2025 Card content with **markdown** support. ::: :::{/cards} Options: :columns: - Column layout: auto (default) - Auto-fit based on card width 2, 3, 4 - Fixed columns 1-2-3 - Responsive (mobile-tablet-desktop) 1-2-3-4 - Responsive with wide breakpoint :gap: - Gap between cards: small, medium (default), large :style: - Card style: default, minimal, bordered :variant: - Variant: navigation (default), info, concept :layout: - Card layout: default, horizontal, portrait, compact Individual Card ({card}) Single card within a cards container. Syntax: :::{card} Card Title :icon: book :link: docs/getting-started :color: blue :image: /hero.jpg :footer: Footer text Card content with **markdown** support. +++ Footer content (alternative to :footer: option) ::: Options: :icon: - Icon name (e.g., book, code, rocket) :link: - Card link URL (path, slug, or id:ref-target) :color: - Color: blue, green, red, yellow, orange, purple, gray, pink, indigo, teal, cyan, violet :image: - Header image URL :footer: - Footer text (or use +++ separator) :pull: - Auto-fetch fields from linked page: title, description, icon, image, date, tags :layout: - Override grid layout: horizontal, portrait, compact Footer Separator: :::{card} Title Body content +++ Footer content ::: Examples Example: Basic Card Grid :::{cards} :columns: 3 :::{card} Getting Started :icon: rocket :link: docs/get-started Learn the basics ::: :::{card} API Reference :icon: code :link: docs/reference/api Complete API docs ::: :::{card} Tutorials :icon: book :link: docs/tutorials Step-by-step tutorials ::: :::{/cards} Example: Responsive Columns :::{cards} :columns: 1-2-3 :gap: large :::{card} Card 1 Content ::: :::{card} Card 2 Content ::: :::{/cards} Example: Cards with Nested Admonitions Named closers eliminate fence-counting for complex nesting: :::{cards} :columns: 2 :::{card} Important Card :::{warning} This feature requires special setup. ::: :::{/card} :::{card} Regular Card Standard content here. :::{/card} :::{/cards} Tip Named Closers Use :::{/name} to explicitly close any container directive, eliminating the need to count colons. Example: Auto-Pull from Linked Pages Use :pull: to automatically fetch metadata from linked pages, reducing content duplication: :::{cards} :columns: 3 :::{card} :link: docs/getting-started/writer-quickstart :pull: title, description ::: :::{card} :link: id:themer-qs :pull: title, description, icon ::: :::{card} Custom Title :link: docs/get-started/quickstart-contributor :pull: description Custom content overrides pulled description. ::: :::{/cards} The :pull: option supports: title - Page title from frontmatter description - Page description from frontmatter icon - Icon from frontmatter image - Image from frontmatter badge - Badge from frontmatter Tip Reference Targets Use id:ref-name syntax to reference pages by their frontmatter id field instead of path. This makes links stable even if you reorganize content. Example: Layout Variants Use :layout: for different card arrangements: :::{cards} :columns: 2 :layout: horizontal :::{card} Feature One :image: /images/feature1.png Image on left, content on right. ::: :::{card} Feature Two :image: /images/feature2.png Great for feature showcases. ::: :::{/cards} Layout options: default - Vertical card (image top, content below) horizontal - Image left, content right portrait - Tall aspect ratio (2:3), great for app screenshots or TCG-style cards compact - Reduced padding for dense reference lists Example: Portrait Cards (TCG/Phone Style) :::{cards} :columns: 3 :layout: portrait :::{card} App Screenshot :image: /images/app-home.png Home screen of our mobile app. ::: :::{card} Dashboard :image: /images/app-dashboard.png Analytics dashboard view. ::: :::{/cards} Tabs Create tabbed content sections for organizing related content. Tab Set ({tab-set}) Container for tab items. Use :::{/tab-set} to close. Aliases: {tabs} Syntax: :::{tab-set} :sync: my-key :::{tab-item} Tab Title :selected: Tab content with **markdown** support. ::: :::{tab-item} Another Tab More content ::: :::{/tab-set} Options: Option Default Description :sync: — Sync key for synchronizing tabs across multiple tab-sets :id: auto-generated Tab set ID for targeting Tab Item ({tab-item}) Individual tab within a tab-set. Aliases: {tab} Syntax: :::{tab-item} Tab Title :selected: :icon: python :badge: Recommended Tab content ::: Options: Option Default Description :selected: false Mark this tab as initially selected :icon: — Icon name to display next to the tab label :badge: — Badge text (e.g., "New", "Beta", "Pro") :disabled: false Mark tab as disabled/unavailable Examples Example: Basic Tabs :::{tab-set} :::{tab-item} Python ```python print("Hello") ``` ::: :::{tab-item} JavaScript ```javascript console.log("Hello"); ``` ::: :::{/tab-set} Example: Synchronized Tabs :::{tab-set} :sync: code-example :::{tab-item} Python Python code ::: :::{/tab-set} :::{tab-set} :sync: code-example :::{tab-item} Python Same Python code (synced) ::: :::{/tab-set} Example: Tabs with Icons and Badges :::{tab-set} :::{tab-item} Python :icon: python :badge: Recommended :selected: Python code here. ::: :::{tab-item} JavaScript :icon: javascript JavaScript code here. ::: :::{tab-item} Ruby :disabled: Ruby support coming soon. ::: :::{/tab-set} Example: Tabs with Nested Admonitions Named closers eliminate fence-counting for complex nesting: :::{tab-set} :::{tab-item} Setup :::{warning} Make sure to backup your data first! ::: Setup instructions here. :::{/tab-item} :::{tab-item} Usage Regular usage content. :::{/tab-item} :::{/tab-set} Tip Named Closers Use :::{/name} to explicitly close any container directive, eliminating the need to count colons. Dropdown Collapsible sections for optional or advanced content. Renders as HTML5 <details>/<summary> elements for native browser support without JavaScript. Aliases: {details} Syntax: :::{dropdown} Title :open: true :icon: info :description: Additional context about what is inside Content with **markdown** support. :::{note} Nested directives work! ::: ::: Options: Option Default Description :open: false Open by default :icon: — Icon name to display next to title :badge: — Badge text (e.g., "New", "Advanced") :color: — Color variant: success, warning, danger, info, minimal :description: — Secondary text below the title to elaborate on content :class: — Additional CSS classes Examples Example: Collapsed by Default :::{dropdown} Advanced Options :icon: settings Click to expand advanced configuration options. ::: Example: Open by Default :::{dropdown} Quick Reference :icon: info :open: true Common commands and shortcuts. ::: Example: With Description :::{dropdown} API Authentication :icon: lock :description: Learn about OAuth 2.0, API keys, and JWT tokens Detailed authentication documentation here. ::: Example: With Badge and Color :::{dropdown} New Features :icon: star :badge: New :color: success Check out the latest features! ::: Example: Warning Dropdown :::{dropdown} Breaking Changes :icon: alert :color: warning :badge: v2.0 Review breaking changes before upgrading. ::: Grid (Sphinx-Design Compatibility) DeprecatedLegacy compatibility layer for Sphinx-Design grid syntax. Grid directives are parsed and converted to cards internally. Syntax: :::{grid} 1 2 2 2 :gutter: 1 :::{grid-item-card} Title :link: docs/getting-started Content ::: :::{/grid} Migration: Replace {grid} with {cards} and {grid-item-card} with {card}: :::{cards} :columns: 1-2-2-2 :gap: small :::{card} Title :link: docs/getting-started Content ::: :::{/cards} Best Practices Card Grids: Use for navigation, feature highlights, or content organization Tabs: Use for related content that doesn't need to be visible simultaneously Dropdowns: Use for optional or advanced content to reduce cognitive load Responsive Design: Use responsive column syntax (1-2-3) for mobile-friendly layouts Auto-Generated Cards For section index pages, consider using {child-cards} instead of manual cards. It automatically generates cards from child sections and pages: :::{child-cards} :columns: 2 :gap: medium :layout: default :include: sections :fields: title, description, icon ::: Options: Option Default Description :columns: auto Column layout (same as {cards}) :gap: medium Gap between cards: small, medium, large :layout: default Card layout: default, horizontal, portrait, compact :include: all What to include: sections, pages, all :fields: title Fields to pull: title, description, icon See Navigation Directives for full documentation. Related Navigation Directives - Auto-generated cards, breadcrumbs, siblings Admonitions - Callout boxes Formatting Directives - Badges, buttons, steps -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 1328 - Reading Time: 7 minutes