Directives Reference

Bengal extends Markdown with powerful directives using:::{name} or ```{name}syntax. Directives provide rich components like callouts, tabs, cards, and more.

Key Terms

Directive: Extended markdown syntax that creates rich components. Bengal supports two syntax styles: fenced (```{name}) and MyST (:::{name}).
Fenced Syntax: Directives using triple backticks (e.g.,```{note}). Used for admonitions, dropdowns, badges, checklists, and include directives.
MyST Syntax: Directives using triple colons (e.g.,:::{card}). Used for cards, tabs, buttons, steps, and list tables. Named after the MyST Markdown specification.

Show 30 more terms

Container Directive: A directive that contains other directives (e.g.,{cards}, {steps}, {tab-set}). Requires 4 fences minimum (::::) and increments for deeper nesting.
Nesting: Placing directives inside other directives. Each nesting level requires incrementing the fence count (container: 4 fences, nested item: 4 fences, deeper nesting:5+ fences).
Admonition: A styled callout box that draws attention to important information. Available in multiple types (note, warning, tip, danger, etc.) with distinct visual styling.
Callout: Another name for an admonition - a visual box that highlights important content separate from the main text flow.
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.
Badge: A small styled label for tags, status indicators, or labels. Renders as an inline element with customizable CSS classes.
Button: A styled link element that appears as a button. Supports colors, sizes, icons, and link targets for calls-to-action.
Steps Container: A container directive ({steps}) that groups multiple step directives together. Requires 4 fences minimum (::::).
Step: An individual step directive ({step}) within a steps container. Contains content for one step in a sequential guide.
Checklist: A styled container for bullet lists and task lists. Provides visual styling for prerequisites, requirements, or task tracking.
Rubric: A pseudo-heading that looks like a heading but doesn't appear in the table of contents. Perfect for API documentation section labels.
List Table: A table created from nested lists, avoiding pipe character conflicts in type annotations. Useful for Python type hints and complex data structures.
Code Tabs: An interactive tabbed interface ({code-tabs}) for displaying code examples in multiple languages. Users can switch between languages with tab navigation.
Data Table: An interactive table directive ({data-table}) with JavaScript-enhanced features like sorting, filtering, and pagination. Requires Tabulator.js in your theme.
Object Tree: Bengal's hierarchical representation of your site structure (Site → Sections → Pages). Navigation directives traverse this tree to generate content automatically.
Child Cards: A directive ({child-cards}) that automatically creates a card grid from a section's child pages and subsections.
Breadcrumbs: A directive ({breadcrumbs}) that generates hierarchical navigation showing the current page's location in the site structure.
Siblings: A directive ({siblings}) that lists pages at the same level as the current page within their shared parent section.
Prev/Next: A directive ({prev-next}) that generates previous/next navigation links within a section.
Related: A directive ({related}) that lists pages with matching tags.
Include Directive: A directive ({include}) that includes markdown files directly in your content. Supports line ranges and relative path resolution.
Literal Include Directive: A directive ({literalinclude}) that includes code files as syntax-highlighted code blocks. Auto-detects language from file extension and supports line ranges, emphasis, and line numbers.
Snippet: A reusable content file (typically markdown or code) that can be included in multiple pages. Organized in dedicated directories likecontent/snippets/.
Path Resolution: The process of finding included files. Bengal resolves paths relative to the current page's directory first, then falls back to the site root.
Path Traversal Prevention: Security feature that prevents including files outside the site root. Blocks../sequences and absolute paths to protect against unauthorized file access.

Quick Reference

Admonitions

Directive	Purpose
`{note}`	Information callout
`{tip}`	Helpful suggestion
`{warning}`	Warning callout
`{caution}`	Cautionary note (renders as warning)
`{danger}`	Critical warning
`{error}`	Error message
`{info}`	Informational content
`{example}`	Example usage
`{success}`	Success message
`{seealso}`	Cross-reference callout

Layout

Directive	Aliases	Purpose
`{cards}`	`{grid}`	Card grid container
`{card}`	`{grid-item-card}`	Individual card
`{child-cards}`	—	Auto-generate cards from children
`{tab-set}`	`{tabs}`	Tab container
`{tab-item}`	`{tab}`	Individual tab
`{dropdown}`	`{details}`	Collapsible section
`{container}`	`{div}`	Generic wrapper

Formatting

Directive	Aliases	Purpose
`{badge}`	`{bdg}`	Styled badge
`{button}`	—	Link button
`{build}`	—	Build-time badge
`{steps}`	—	Step-by-step guide
`{step}`	—	Individual step
`{checklist}`	—	Styled checklist
`{rubric}`	—	Pseudo-heading (not in TOC)
`{list-table}`	—	Table from lists

Content Reuse

Directive	Purpose
`{include}`	Include markdown file
`{literalinclude}`	Include code file with syntax highlighting

Interactive

Directive	Aliases	Purpose
`{code-tabs}`	`{code_tabs}`	Multi-language code tabs
`{data-table}`	—	Interactive data table

Media Embeds

Directive	Purpose
`{youtube}`	YouTube embed (privacy-enhanced by default)
`{vimeo}`	Vimeo embed (DNT by default)
`{tiktok}`	TikTok short-form video embed
`{spotify}`	Spotify tracks, albums, playlists, podcasts
`{soundcloud}`	SoundCloud tracks, playlists
`{video}`	Self-hosted HTML5 video
`{audio}`	Self-hosted HTML5 audio
`{figure}`	Image with caption
`{gist}`	GitHub Gist embed
`{codepen}`	CodePen embed
`{codesandbox}`	CodeSandbox embed
`{stackblitz}`	StackBlitz embed
`{asciinema}`	Terminal recording
`{gallery}`	Image gallery

Directive	Purpose
`{breadcrumbs}`	Breadcrumb navigation trail
`{siblings}`	Sibling page links
`{prev-next}`	Previous/next navigation links
`{related}`	Related pages by shared tags

Versioning

Directive	Aliases	Purpose
`{since}`	`{versionadded}`	Mark feature as new
`{deprecated}`	`{versionremoved}`	Mark feature as deprecated
`{changed}`	`{versionchanged}`	Mark behavior change

Other

Directive	Aliases	Purpose
`{glossary}`	—	Render terms from glossary data
`{target}`	`{anchor}`	Create link target
`{icon}`	`{svg-icon}`	Inline SVG icon
`{example-label}`	—	Example label for documentation
`{marimo}`	—	Interactive Python notebook

Directive Syntax

Bengal supports MyST-style directive syntax using triple colons:::. Most directives use this format:

:::{directive-name} Optional Title
:option: value

Content here
:::

Named Closers

For nested directives, use named closers (:::{/name}) to avoid ambiguity:

:::{cards}
:columns: 3

:::{card} First Card
Content
:::{/card}

:::{card} Second Card
Content
:::{/card}

:::{/cards}

Deep Nesting

Named closers are particularly useful for deeply nested structures:

:::{steps}

:::{step} First Step
:::{tip}
Remember to check the logs!
:::
:::{/step}

:::{step} Second Step
:::{warning}
This step requires admin access.
:::
:::{/step}

:::{/steps}

Directive Options

Options are specified with:option: valuesyntax on separate lines after the directive name:

:::{card} Card Title
:icon: rocket
:link: /docs/quickstart/
:color: blue

Card content here.
:::

Boolean options can omit the value:

:::{tab-item} Python
:selected:

Python code here.
:::

Common Options

Many directives support these common options:

:class:- Custom CSS class
:id:- Element ID
:title:- Title text (alternative to title in directive name)

Examples

Basic Admonition

:::{note}
This is a note with **markdown** support.
:::

Card Grid

:::{cards}
:columns: 3

:::{card} Card 1
:icon: book
:link: docs/getting-started

Content here
:::

:::{card} Card 2
Content here
:::

:::{/cards}

Tabs

:::{tab-set}

:::{tab-item} Python
```python
print("Hello")
```
:::

:::{tab-item} JavaScript
```javascript
console.log("Hello");
```
:::

:::{/tab-set}

Glossary Directive

The{glossary} directive renders terms from a centralized glossary data file (data/glossary.yaml) as a styled definition list. Filter terms by tags to show relevant definitions for each page.

Syntax

:::{glossary}
:tags: directives, core
:sorted: true
:collapsed: true
:limit: 3
:::

Options

Option	Default	Description
`:tags:`	(required)	Comma-separated tags to filter terms (OR logic)
`:sorted:`	`false`	Sort terms alphabetically
`:show-tags:`	`false`	Display tag badges under each term
`:collapsed:`	`false`	Wrap in collapsible`<details>`element
`:limit:`	(all)	Show only first N terms; remaining in expandable section
`:source:`	`data/glossary.yaml`	Custom glossary file path

Examples

Example: Basic Usage

Show terms tagged with "directives":

:::{glossary}
:tags: directives
:::

Example: Progressive Disclosure

Show first 3 terms, rest expandable:

:::{glossary}
:tags: directives, core
:limit: 3
:::

Example: Fully Collapsed

Entire glossary in collapsible section:

:::{glossary}
:tags: formatting
:collapsed: true
:::

Example: Both Options

Collapsed, with limited terms when expanded:

:::{glossary}
:tags: layout
:collapsed: true
:limit: 2
:::

Glossary Data Format

Terms are defined indata/glossary.yaml:

terms:
  - term: Directive
    definition: Extended markdown syntax using `{name}` that creates rich components.
    tags: [directives, core]

  - term: Admonition
    definition: A styled callout box for **important** information.
    tags: [directives, admonitions]

Note: Definitions support inline markdown: backticks for code, **bold**, and *italic*.

Next Steps

Browse directive categories above for detailed syntax
See Content Reuse for include/literalinclude strategies
Check Writer Quickstart for markdown basics

Directives Reference

Key Terms

Quick Reference

Admonitions

Layout

Formatting

Content Reuse

Interactive

Media Embeds

Navigation

Versioning

Other

Directive Syntax

Named Closers

Deep Nesting

Directive Options

Categories

Common Options

Examples

Basic Admonition

Card Grid

Tabs

Glossary Directive

Syntax

Options

Examples

Glossary Data Format

Next Steps