# Directives Reference URL: /bengal/docs/reference/directives/ Section: directives Description: Complete reference for all available markdown directives in Bengal --- > For a complete page index, fetch /bengal/llms.txt. 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 like`content/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 ### Navigation 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: value`syntax 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. ::: ``` ## Categories Admonitions Reference for admonition directives (note, warning, tip, danger, etc.) (/bengal/docs/reference/directives/admonitions/) Layout Directives Reference for layout directives (cards, tabs, dropdown, grid) (/bengal/docs/reference/directives/layout/) Formatting Directives Reference for formatting directives (badge, icon, button, steps, checklist, rubric, list-table) (/bengal/docs/reference/directives/formatting/) Interactive Directives Reference for interactive directives (code-tabs, data-table) (/bengal/docs/reference/directives/interactive/) Content Reuse Directives Reference for content reuse directives (include, literalinclude) (/bengal/docs/reference/directives/content-reuse/) Media Directives Reference for media embed directives (YouTube, Vimeo, TikTok, Spotify, SoundCloud, video, audio, figure, code playgrounds, terminal recordings) (/bengal/docs/reference/directives/media/) Navigation Directives Reference for navigation directives (child-cards, breadcrumbs, siblings, prev-next, related) (/bengal/docs/reference/directives/navigation/) Versioning Directives Directives for marking version-specific documentation content (/bengal/docs/reference/directives/versioning/) ## 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`
`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 in`data/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 (/bengal/docs/reference/directives/content-reuse/) for include/literalinclude strategies - Check Writer Quickstart (/bengal/docs/get-started/quickstart-writer/) for markdown basics ## In This Section Admonitions (/bengal/docs/reference/directives/admonitions/) Reference for admonition directives (note, warning, tip, danger, etc.) Content Reuse Directives (/bengal/docs/reference/directives/content-reuse/) Reference for content reuse directives (include, literalinclude) Formatting Directives (/bengal/docs/reference/directives/formatting/) Reference for formatting directives (badge, icon, button, steps, checklist, rubric, list-table) Interactive Directives (/bengal/docs/reference/directives/interactive/) Reference for interactive directives (code-tabs, data-table) Layout Directives (/bengal/docs/reference/directives/layout/) Reference for layout directives (cards, tabs, dropdown, grid) Media Directives (/bengal/docs/reference/directives/media/) Reference for media embed directives (YouTube, Vimeo, TikTok, Spotify, SoundCloud, video, audio, figure, code playgrounds, terminal recordings) Navigation Directives (/bengal/docs/reference/directives/navigation/) Reference for navigation directives (child-cards, breadcrumbs, siblings, prev-next, related) Versioning Directives (/bengal/docs/reference/directives/versioning/) Directives for marking version-specific documentation content Related Pages Functions (/bengal/docs/theming/templating/kida/syntax/functions/) Reusable template components that automatically access outer variables Related reference (/bengal/tags/reference/) directives (/bengal/tags/directives/) markdown (/bengal/tags/markdown/) syntax (/bengal/tags/syntax/)