Every directive category on one page — live examples you can copy into your own
content. For option reference and edge cases, see the category pages linked at
the bottom.
Note
Do I need this? Skim this page when you want to see what Bengal can render.
Use category reference pages when you need exhaustive option lists.
Admonitions
Note
Informational callout with markdown support.
Tip
Helpful suggestion — great for shortcuts and best practices.
Warning
Something may break or needs attention before you proceed.
Danger
Critical — data loss, security, or irreversible action possible.
New in 0.4.0Deprecated since 0.4.0Changed in 0.4.0
Glossary (progressive disclosure)
Key Terms (33)
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.