Module

directives.builtins.tabs

Tab directives for tabbed content.

Provides tabbed content sections with full markdown support including nested directives, code blocks, and admonitions.

Supports two rendering modes:

  • "enhanced" (default): JavaScript-based tabs with data-tab-target
  • "css_state_machine": URL-driven tabs using :target CSS selector

Tab-Item Options: :selected: - Whether this tab is initially selected :icon: - Icon name to show next to tab label :badge: - Badge text (e.g., "New", "Beta", "Pro") :disabled: - Mark tab as disabled/unavailable

Example:

Content for Python tab.

Content for JavaScript tab.

Thread Safety:

Stateless handlers. Safe for concurrent use across threads.

5Classes1Function

Classes

TabItemOptions 5 ▼
Options for tab-item directive.
Bases: StyledOptions

Options for tab-item directive.

Attributes

Name Type Description
selected bool

Whether this tab is initially selected
icon str | None

Icon name to show next to tab label
badge str | None

Badge text (e.g., "New", "Beta", "Pro")
disabled bool

Mark tab as disabled/unavailable
sync str | None —
TabSetOptions 3 ▼
Options for tab-set directive.
Bases: StyledOptions

Options for tab-set directive.

Attributes

Name Type Description
id str | None

Unique ID for the tab set
sync str | None

Sync key for synchronizing tabs across multiple tab-sets
mode str | None

Rendering mode - "enhanced" (JS) or "css_state_machine" (URL-driven)
TabItemData 6 ▼
Data extracted from a rendered tab-item div.

Data extracted from a rendered tab-item div.

Attributes

Name Type Description
title str —
selected str —
icon str —
badge str —
disabled str —
content str —
TabItemDirective 7 ▼
Handler for tab-item directive. Must be inside a tab-set container. Thread Safety: Stateless …

Handler for tab-item directive.

Must be inside a tab-set container.

Thread Safety:

Stateless handler. Safe for concurrent use.

Attributes

Name Type Description
names ClassVar[tuple[str, ...]] —
token_type ClassVar[str] —
contract ClassVar[DirectiveContract | None] —
options_class ClassVar[type[TabItemOptions]] —
preserves_raw_content ClassVar[bool] —

Methods

parse 6 Directive[TabItemOptions] ▼
Build tab-item AST node.
def parse(self, name: str, title: str | None, options: TabItemOptions, content: str, children: Sequence[Block], location: SourceLocation) -> Directive[TabItemOptions]
Parameters
Name Type Description
name —
title —
options —
content —
children —
location —
Returns
Directive[TabItemOptions]
render 3 ▼
Render tab-item to HTML. Creates a wrapper div with metadata that the parent t…
def render(self, node: Directive[TabItemOptions], rendered_children: str, sb: StringBuilder) -> None

Render tab-item to HTML.

Creates a wrapper div with metadata that the parent tab-set will parse to build the navigation and panels.

Parameters
Name Type Description
node —
rendered_children —
sb —
TabSetDirective 10 ▼
Handler for tab-set container directive. Contains tab-item children that form a tabbed interface. …

Handler for tab-set container directive.

Contains tab-item children that form a tabbed interface.

Thread Safety:

Stateless handler. Safe for concurrent use.

Attributes

Name Type Description
names ClassVar[tuple[str, ...]] —
token_type ClassVar[str] —
contract ClassVar[DirectiveContract | None] —
options_class ClassVar[type[TabSetOptions]] —
preserves_raw_content ClassVar[bool] —

Methods

parse 6 Directive[TabSetOptions] ▼
Build tab-set AST node.
def parse(self, name: str, title: str | None, options: TabSetOptions, content: str, children: Sequence[Block], location: SourceLocation) -> Directive[TabSetOptions]
Parameters
Name Type Description
name —
title —
options —
content —
children —
location —
Returns
Directive[TabSetOptions]
render 3 ▼
Render tab-set to HTML. Extracts tab items from rendered children and builds n…
def render(self, node: Directive[TabSetOptions], rendered_children: str, sb: StringBuilder) -> None

Render tab-set to HTML.

Extracts tab items from rendered children and builds navigation + content panels.

Parameters
Name Type Description
node —
rendered_children —
sb —
Internal Methods 3 ▼
_render_enhanced 4 ▼
Render JavaScript-enhanced tabs (default mode).
def _render_enhanced(self, tab_id: str, sync_key: str, matches: list[TabItemData], sb: StringBuilder) -> None
Parameters
Name Type Description
tab_id —
sync_key —
matches —
sb —
_render_css_state_machine 4 ▼
Render CSS state machine tabs (URL-driven, no JS required).
def _render_css_state_machine(self, tab_id: str, sync_key: str, matches: list[TabItemData], sb: StringBuilder) -> None
Parameters
Name Type Description
tab_id —
sync_key —
matches —
sb —
_slugify 1 str ▼
Convert text to URL-safe slug.
def _slugify(self, text: str) -> str
Parameters
Name Type Description
text —
Returns
str

Functions

_extract_tab_items 1 list[TabItemData] ▼
Extract tab-item divs from rendered HTML, handling nested divs correctly.
def _extract_tab_items(text: str) -> list[TabItemData]
Parameters
Name Type Description
text str

Rendered HTML containing tab-item divs
Returns
list[TabItemData]