# Layout Directives URL: /docs/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: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17:::{cards} :columns: 3 :gap: medium :style: default :variant: navigation :::{card} Card Title :icon: book :link: /docs/ :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: 1 2 3 4 5 6 7 8 9 10 11 12:::{card} Card Title :icon: book :link: /docs/ :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 :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: 1 2 3 4 5:::{card} Title Body content +++ Footer content ::: Examples Basic Card Grid: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25:::{cards} :columns: 3 :::{card} Getting Started :icon: rocket :link: /docs/get-started/ Learn the basics ::: :::{card} API Reference :icon: code :link: /api/ Complete API docs ::: :::{card} Tutorials :icon: book :link: /docs/tutorials/ Step-by-step tutorials ::: :::{/cards} Responsive Columns: 1 2 3 4 5 6 7 8 9 10 11 12 13:::{cards} :columns: 1-2-3 :gap: large :::{card} Card 1 Content ::: :::{card} Card 2 Content ::: :::{/cards} Cards with Nested Admonitions: Named closers eliminate fence-counting for complex nesting: 1 2 3 4 5 6 7 8 9 10 11 12 13 14:::{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. Auto-Pull from Linked Pages: Use :pull: to automatically fetch metadata from linked pages, reducing content duplication: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21:::{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/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 date - Page date tags - Page tags 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. Layout Variants: Use :layout: for different card arrangements: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17:::{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 Portrait Cards (TCG/Phone Style): 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17:::{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. Syntax: 1 2 3 4 5 6 7 8 9 10 11 12 13 14:::{tab-set} :sync: my-key :::{tab-item} Tab Title :selected: Tab content with **markdown** support. ::: :::{tab-item} Another Tab More content ::: :::{/tab-set} Options: :sync: - Sync key for multiple tab-sets (same key = synchronized selection) :id: - Tab set ID Tab Item ({tab-item}) Individual tab within a tab-set. Syntax: 1 2 3 4 5:::{tab-item} Tab Title :selected: Tab content ::: Options: :selected: - Mark this tab as initially selected (no value needed) Examples Basic Tabs: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15:::{tab-set} :::{tab-item} Python ```python print("Hello") ``` ::: :::{tab-item} JavaScript ```javascript console.log("Hello"); ``` ::: :::{/tab-set} Synchronized Tabs: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17:::{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} Tabs with Nested Admonitions: Named closers eliminate fence-counting for complex nesting: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15:::{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. Syntax: 1 2 3 4 5 6 7 8 9 10:::{dropdown} Title :open: true :icon: info Content with **markdown** support. :::{note} Nested directives work! ::: ::: Options: :open: - Open by default: true, false (default) :icon: - Icon name to display next to title (e.g., info, settings, star) :badge: - Badge text (e.g., "New", "Advanced") :color: - Color variant: success, warning, danger, info, minimal :class: - Additional CSS classes Alias: {details} works the same as {dropdown}. Examples Collapsed by Default: 1 2 3 4:::{dropdown} Advanced Options :icon: settings Click to expand advanced configuration options. ::: Open by Default: 1 2 3 4 5 6:::{dropdown} Quick Reference :icon: info :open: true Common commands and shortcuts. ::: With Badge and Color: 1 2 3 4 5 6 7:::{dropdown} New Features :icon: star :badge: New :color: success Check out the latest features! ::: Grid (Sphinx-Design Compatibility) Compatibility layer for Sphinx-Design grid syntax. Syntax: 1 2 3 4 5 6 7 8 9 10:::{grid} 1 2 2 2 :gutter: 1 :::{grid-item-card} Title :link: /docs/ Content ::: :::{/grid} Note Note Prefer {cards} / {card} for new content. Grid directives convert to cards internally. 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: 1 2 3 4 5:::{child-cards} :columns: 2 :include: sections :fields: 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: 1350 - Reading Time: 7 minutes