Layout Directives

Reference for layout directives (cards, tabs, dropdown, grid)

6 min read 1111 words

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, orid: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}

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

Reference Targets

Useid:ref-namesyntax to reference pages by their frontmatteridfield 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}

Named Closers

Use:::{/name}to explicitly close any container directive, eliminating the need to count colons.

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

Prefer{cards}/{card}for new content. Grid directives convert to cards internally.

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:

1
2
3
4
5
:::{child-cards}
:columns: 2
:include: sections
:fields: title, description, icon
:::

See Navigation Directives for full documentation.