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}

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

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:

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:

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}

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:

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)

Legacy 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

1. Card Grids: Use for navigation, feature highlights, or content organization
2. Tabs: Use for related content that doesn't need to be visible simultaneously
3. Dropdowns: Use for optional or advanced content to reduce cognitive load
4. 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:

See Navigation Directives for full documentation.

Related

• Navigation Directives - Auto-generated cards, breadcrumbs, siblings
• Admonitions - Callout boxes
• Formatting Directives - Badges, buttons, steps