dropdown

rendering.plugins.directives.dropdown

Dropdown directive for Mistune.

Provides collapsible sections with markdown support including nested directives and code blocks.

Architecture:

Migrated to BengalDirective base class as part of directive system v2.
Uses typed DropdownOptions and encapsulated render method.

Related:

bengal/rendering/plugins/directives/base.py: BengalDirective
RFC: plan/active/rfc-directive-system-v2.md

Classes

DropdownOptions dataclass

Options for dropdown directive.

Inherits from DirectiveOptions

Attributes

Name	Type	Description
`open`	`bool`	Whether dropdown is initially open (expanded)
`icon`	`str`	Icon name to display next to the title
`badge`	`str`	Badge text (e.g., "New", "Advanced", "Beta")
`color`	`str`	Color variant (success, warning, danger, info, minimal)
`description`	`str`	Secondary text below the title to elaborate on the dropdown content
`css_class`	`str`	Additional CSS classes for the container
`_field_aliases`	`ClassVar[dict[str, str]]`

DropdownDirective

Collapsible dropdown directive with markdown support. Syntax: :::{dropdown} Title :open: t…

Collapsible dropdown directive with markdown support.

Syntax:

:::{dropdown} Title
:open: true
:icon: info
:badge: Advanced
:color: info
:description: Brief explanation of the dropdown content
:class: custom-class

Content with **markdown**, code blocks, etc.

:::{note}
Even nested admonitions work!
:::
:::

Or using the HTML5 semantic alias: :::{details} Summary Text Content :::

Aliases:

dropdown: Primary name
details: HTML5 semantic alias (renders as <details>)

Options:

:open: true/false - Whether initially expanded (default: false)
:icon: string - Icon name to display next to title
:badge: string - Badge text (e.g., "New", "Advanced")
:color: string - Color variant (success, warning, danger, info, minimal)
:description: string - Secondary text to elaborate on dropdown content
:class: string - Additional CSS classes

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 dropdown token from parsed components.

5 DirectiveToken

def parse_directive(self, title: str, options: DropdownOptions, content: str, children: list[Any], state: Any) -> DirectiveToken

Build dropdown token from parsed components.

Parameters 5

`title`	`str`	Dropdown title (text after directive name)
`options`	`DropdownOptions`	Typed dropdown options
`content`	`str`	Raw content string (unused, children are already parsed)
`children`	`list[Any]`	Parsed nested content tokens
`state`	`Any`	Parser state

Returns

DirectiveToken —

DirectiveToken for the dropdown

render

Render dropdown to HTML. Renders as HTML5 <details>/<summary> elements for nat…

2 str

def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render dropdown to HTML.

Renders as HTML5 <details>/<summary> elements for native collapsible behavior without JavaScript.

Parameters 2

`renderer`	`Any`	Mistune renderer instance
`text`	`str`	Pre-rendered children HTML **attrs: Token attributes (title, open, icon, badge, color, css_class)

Returns

str —

HTML string

Functions

_render_dropdown_icon

Render dropdown icon using shared icon utilities.

2 str

def _render_dropdown_icon(icon_name: str, dropdown_title: str = '') -> str

Render dropdown icon using shared icon utilities.

Parameters 2

Name	Type	Default	Description
`icon_name`	`str`	—	Name of the icon to render
`dropdown_title`	`str`	`''`	Title of the dropdown (for warning context)

Returns

str —

SVG HTML string, or empty string if icon not found

render_dropdown

Legacy render function for backward compatibility. Deprecated: Use DropdownDirective class which e…

2 str

def render_dropdown(renderer: Any, text: str, **attrs: Any) -> str

Legacy render function for backward compatibility.

Deprecated: Use DropdownDirective class which encapsulates rendering.

Parameters 2

Name	Type	Default	Description
`renderer`	`Any`	—	Mistune renderer instance
`text`	`str`	—	Pre-rendered children HTML **attrs: Token attributes

Returns

str —

HTML string