Module

rendering.plugins.directives.cards

Cards directive for Bengal SSG.

Provides a modern, simple card grid system with auto-layout and responsive columns.

Architecture:

Migrated to BengalDirective base class with DirectiveContract validation.
  • CardsDirective: allows card children
  • CardDirective: requires_parent=["cards_grid"] (optional, not enforced)

Syntax (preferred - named closers):

:::{cards}
:columns: 3
:gap: medium

:::{card} Card Title
:icon: book
:link: /docs/
:description: Brief summary shown below the title
:badge: New
Card content with **markdown** support.
:::{/card}
:::{/cards}

Card Options:

:icon: - Icon name displayed in card header
:link: - URL or page reference (makes card clickable)
:description: - Brief summary shown below the title
:badge: - Badge text (e.g., "New", "Beta", "Pro")
:color: - Color theme (blue, green, red, yellow, etc.)
:image: - Header image URL
:footer: - Footer content
:pull: - Fields to pull from linked page (title, description, icon)
:layout: - Layout override (default, horizontal, portrait, compact)
View source
8 Classes 17 Functions

Classes

CardsOptions dataclass
Options for cards grid directive.
0

Options for cards grid directive.

Inherits from DirectiveOptions

Attributes

Name Type Description
columns str

Column layout ("auto", "1-6", or responsive "1-2-3")
gap str

Grid gap (small, medium, large)
style str

Visual style (default, minimal, bordered)
variant str

Card variant (navigation, info, concept)
layout str

Card layout (default, horizontal, portrait, compact)
_allowed_values ClassVar[dict[str, list[str]]]
CardsDirective
Cards grid container directive. Creates a responsive grid of cards with sensible defaults. Syntax…
2

Cards grid container directive.

Creates a responsive grid of cards with sensible defaults.

Syntax:

::::{cards}
:columns: 3
:gap: medium
:style: default
:variant: navigation
:layout: default

:::{card} Title
Content
:::
::::

Columns accept:

  • "auto" - Auto-fit layout
  • "2", "3", "4" - Fixed columns
  • "1-2-3" - Responsive (mobile-tablet-desktop)
Inherits from BengalDirective

Attributes

Name Type Description
NAMES ClassVar[list[str]]
TOKEN_TYPE ClassVar[str]
OPTIONS_CLASS ClassVar[type[DirectiveOptions]]
CONTRACT ClassVar[DirectiveContract]
DIRECTIVE_NAMES ClassVar[list[str]]

Methods 2

parse_directive
Build cards grid token.
5 DirectiveToken 
def parse_directive(self, title: str, options: CardsOptions, content: str, children: list[Any], state: Any) -> DirectiveToken

Build cards grid token.

Parameters 5
title str
options CardsOptions
content str
children list[Any]
state Any
Returns

DirectiveToken

render
Render cards grid container to HTML.
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render cards grid container to HTML.

Parameters 2
renderer Any
text str
Returns

str

CardOptions dataclass
Options for individual card directive.
0

Options for individual card directive.

Inherits from DirectiveOptions

Attributes

Name Type Description
icon str

Icon name
link str

URL or page reference
description str

Brief summary shown below the title
badge str

Badge text (e.g., "New", "Beta", "Pro")
color str

Color theme (blue, green, red, etc.)
image str

Header image URL
footer str

Footer content
pull str

Fields to pull from linked page (comma-separated)
layout str

Layout override (default, horizontal, portrait, compact)
_allowed_values ClassVar[dict[str, list[str]]]
CardDirective
Individual card directive (nested in cards). Syntax: :::{card} Card Title :icon: book …
2

Individual card directive (nested in cards).

Syntax:

:::{card} Card Title
:icon: book
:link: /docs/
:color: blue
:image: /hero.jpg
:footer: Updated 2025
:pull: title, description

Card content with **markdown** support.
:::

Footer separator:

:::{card} Title
Body content
+++
Footer content
:::

Contract:

Typically nested inside :::{cards}, but can be standalone.
Inherits from BengalDirective

Attributes

Name Type Description
NAMES ClassVar[list[str]]
TOKEN_TYPE ClassVar[str]
OPTIONS_CLASS ClassVar[type[DirectiveOptions]]
CONTRACT ClassVar[DirectiveContract]
DIRECTIVE_NAMES ClassVar[list[str]]

Methods 2

parse_directive
Build card token, handling footer separator.
5 DirectiveToken 
def parse_directive(self, title: str, options: CardOptions, content: str, children: list[Any], state: Any) -> DirectiveToken

Build card token, handling footer separator.

Parameters 5
title str
options CardOptions
content str
children list[Any]
state Any
Returns

DirectiveToken

render
Render individual card to HTML.
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render individual card to HTML.

Parameters 2
renderer Any
text str
Returns

str

GridDirective
Grid layout compatibility layer. Converts legacy grid syntax to modern cards syntax. Not migrated …
2

Grid layout compatibility layer.

Converts legacy grid syntax to modern cards syntax. Not migrated to BengalDirective since it's a compatibility shim.

Old syntax:

::::{grid} 1 2 2 2
:gutter: 1
::::
Inherits from DirectivePlugin

Attributes

Name Type Description
DIRECTIVE_NAMES ClassVar[list[str]]

Methods 1

parse
Parse grid directive (compatibility mode).
3 dict[str, Any] 
def parse(self, block: Any, m: Match[str], state: Any) -> dict[str, Any]

Parse grid directive (compatibility mode).

Parameters 3
block Any
m Match[str]
state Any
Returns

dict[str, Any]

Internal Methods 1
__call__
Register the directive with mistune.
2 None 
def __call__(self, directive: Any, md: Any) -> None

Register the directive with mistune.

Parameters 2
directive Any
md Any
GridItemCardDirective
Grid item card compatibility layer. Converts old syntax to modern card syntax. Not migrated to Ben…
2

Grid item card compatibility layer.

Converts old syntax to modern card syntax. Not migrated to BengalDirective since it's a compatibility shim.

Inherits from DirectivePlugin

Attributes

Name Type Description
DIRECTIVE_NAMES ClassVar[list[str]]

Methods 1

parse
Parse grid-item-card directive (compatibility mode).
3 dict[str, Any] 
def parse(self, block: Any, m: Match[str], state: Any) -> dict[str, Any]

Parse grid-item-card directive (compatibility mode).

Parameters 3
block Any
m Match[str]
state Any
Returns

dict[str, Any]

Internal Methods 1
__call__
Register the directive with mistune.
2 None 
def __call__(self, directive: Any, md: Any) -> None

Register the directive with mistune.

Parameters 2
directive Any
md Any
ChildCardsOptions dataclass
Options for child-cards directive.
0

Options for child-cards directive.

Inherits from DirectiveOptions

Attributes

Name Type Description
columns str

Column layout
gap str

Grid gap
include str

What to include (sections, pages, all)
fields str

Fields to pull (comma-separated)
layout str

Card layout
style str

Visual style
_allowed_values ClassVar[dict[str, list[str]]]
ChildCardsDirective
Auto-generate cards from current page's child sections/pages. Syntax: :::{child-cards} :co…
2

Auto-generate cards from current page's child sections/pages.

Syntax:

:::{child-cards}
:columns: 3
:include: sections
:fields: title, description, icon
:::
Inherits from BengalDirective

Attributes

Name Type Description
NAMES ClassVar[list[str]]
TOKEN_TYPE ClassVar[str]
OPTIONS_CLASS ClassVar[type[DirectiveOptions]]
DIRECTIVE_NAMES ClassVar[list[str]]

Methods 2

parse_directive
Build child-cards token.
5 DirectiveToken 
def parse_directive(self, title: str, options: ChildCardsOptions, content: str, children: list[Any], state: Any) -> DirectiveToken

Build child-cards token.

Parameters 5
title str
options ChildCardsOptions
content str
children list[Any]
state Any
Returns

DirectiveToken

render
Render child cards by walking the page object tree.
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render child cards by walking the page object tree.

Parameters 2
renderer Any
text str
Returns

str

Functions

_normalize_columns
Normalize columns specification.
1 str 
def _normalize_columns(columns: str) -> str

Normalize columns specification.

Parameters 1

Name Type Default Description
columns str —

Returns

str

_convert_legacy_columns
Convert legacy column breakpoints to our format.
1 str 
def _convert_legacy_columns(title: str) -> str

Convert legacy column breakpoints to our format.

Parameters 1

Name Type Default Description
title str —

Returns

str

_convert_legacy_gutter
Convert legacy gutter to gap format.
1 str 
def _convert_legacy_gutter(gutter: str) -> str

Convert legacy gutter to gap format.

Parameters 1

Name Type Default Description
gutter str —

Returns

str

_extract_octicon
Extract octicon from title.
1 tuple[str, str] 
def _extract_octicon(title: str) -> tuple[str, str]

Extract octicon from title.

Parameters 1

Name Type Default Description
title str —

Returns

tuple[str, str]

_pull_from_linked_page
Pull metadata from a linked page.
3 dict[str, Any] 
def _pull_from_linked_page(renderer: Any, link: str, fields: list[str]) -> dict[str, Any]

Pull metadata from a linked page.

Parameters 3

Name Type Default Description
renderer Any —
link str —
fields list[str] —

Returns

dict[str, Any]

_extract_page_fields
Extract requested fields from a page object.
2 dict[str, Any] 
def _extract_page_fields(page: Any, fields: list[str]) -> dict[str, Any]

Extract requested fields from a page object.

Parameters 2

Name Type Default Description
page Any —
fields list[str] —

Returns

dict[str, Any]

_resolve_page
Resolve a link to a page object.
3 Any 
def _resolve_page(xref_index: dict[str, Any], link: str, current_page_dir: str | None = None) -> Any

Resolve a link to a page object.

Parameters 3

Name Type Default Description
xref_index dict[str, Any] —
link str —
current_page_dir str | None None

Returns

Any

_resolve_link_url
Resolve a link reference to a URL.
2 str 
def _resolve_link_url(renderer: Any, link: str) -> str

Resolve a link reference to a URL.

Parameters 2

Name Type Default Description
renderer Any —
link str —

Returns

str

_render_icon
Render icon using Bengal SVG icons.
2 str 
def _render_icon(icon_name: str, card_title: str = '') -> str

Render icon using Bengal SVG icons.

Parameters 2

Name Type Default Description
icon_name str —

Name of the icon to render
card_title str ''

Title of the card (for warning context)

Returns

str —

SVG HTML string, or empty string if not found

_collect_children
Collect child sections/pages from section.
3 list[dict[str, Any]] 
def _collect_children(section: Any, current_page: Any, include: str) -> list[dict[str, Any]]

Collect child sections/pages from section.

Parameters 3

Name Type Default Description
section Any —
current_page Any —
include str —

Returns

list[dict[str, Any]]

_warn_mixed_weights
Warn if some children have explicit weights and others don't.
2 None 
def _warn_mixed_weights(children: list[dict[str, Any]], current_page: Any) -> None

Warn if some children have explicit weights and others don't.

Parameters 2

Name Type Default Description
children list[dict[str, Any]] —
current_page Any —
_get_section_url
Get URL for a section.
1 str 
def _get_section_url(section: Any) -> str

Get URL for a section.

Parameters 1

Name Type Default Description
section Any —

Returns

str

_render_child_card
Render a single card for a child section/page.
4 str 
def _render_child_card(child: dict[str, Any], fields: list[str], layout: str, escape_html: Callable[[str], str]) -> str

Render a single card for a child section/page.

Parameters 4

Name Type Default Description
child dict[str, Any] —
fields list[str] —
layout str —
escape_html Callable[[str], str] —

Returns

str

_escape_html
Escape HTML special characters.
1 str 
def _escape_html(text: str) -> str

Escape HTML special characters.

Parameters 1

Name Type Default Description
text str —

Returns

str

render_cards_grid
Legacy render function for backward compatibility.
2 str 
def render_cards_grid(renderer: Any, text: str, **attrs: Any) -> str

Legacy render function for backward compatibility.

Parameters 2

Name Type Default Description
renderer Any —
text str —

Returns

str

render_card
Legacy render function for backward compatibility.
2 str 
def render_card(renderer: Any, text: str, **attrs: Any) -> str

Legacy render function for backward compatibility.

Parameters 2

Name Type Default Description
renderer Any —
text str —

Returns

str

render_child_cards
Legacy render function for backward compatibility.
2 str 
def render_child_cards(renderer: Any, text: str, **attrs: Any) -> str

Legacy render function for backward compatibility.

Parameters 2

Name Type Default Description
renderer Any —
text str —

Returns

str