# Directives Reference URL: /docs/reference/directives/ Section: directives Tags: reference, directives, markdown, syntax -------------------------------------------------------------------------------- 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 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 Directive Syntax Purpose Category {note} ```{note} Information callout Admonitions {warning} ```{warning} Warning callout Admonitions {tip} ```{tip} Tip callout Admonitions {danger} ```{danger} Danger callout Admonitions {cards} :::{cards} Card grid layout Layout {card} :::{card} Individual card Layout {tab-set} :::{tab-set} Tab container Layout {tab-item} :::{tab-item} Individual tab Layout {dropdown} ```{dropdown} Collapsible section Layout {code-tabs} ```{code-tabs} Multi-language code Interactive {badge} ```{badge} Styled badge Formatting {button} :::{button} Link button Formatting {steps} :::{steps} Step-by-step guide Formatting {step} :::{step} Individual step Formatting {checklist} ```{checklist} Styled checklist Formatting {rubric} ```{rubric} Pseudo-heading Formatting {include} ```{include} Include markdown file Content Reuse {literalinclude} ```{literalinclude} Include code file Content Reuse {list-table} :::{list-table} Table from lists Formatting {data-table} :::{data-table} Interactive data table Interactive {youtube} :::{youtube} YouTube embed (privacy default) Media {vimeo} :::{vimeo} Vimeo embed (DNT default) Media {video} :::{video} Self-hosted HTML5 video Media {figure} :::{figure} Image with caption Media {audio} :::{audio} Self-hosted HTML5 audio Media {gist} :::{gist} GitHub Gist embed Media {codepen} :::{codepen} CodePen embed Media {codesandbox} :::{codesandbox} CodeSandbox embed Media {stackblitz} :::{stackblitz} StackBlitz embed Media {asciinema} :::{asciinema} Terminal recording Media {child-cards} :::{child-cards} Auto-generate cards from children Navigation {breadcrumbs} :::{breadcrumbs} Breadcrumb navigation Navigation {siblings} :::{siblings} Sibling page list Navigation {prev-next} :::{prev-next} Prev/next links Navigation {related} :::{related} Related pages by tags Navigation {glossary} :::{glossary} Render terms from glossary data Data {icon} ❓ Inline SVG icon Icons Directive Syntax Bengal supports two directive syntax styles: Fenced Syntax (3 backticks) 1 2 3 4 5:::{directive-name} Optional Title :option: value Content here ::: Used for: Admonitions, dropdowns, badges, checklists, code-tabs, include, literalinclude, rubric MyST Syntax (3 colons) 1 2 3 4 5:::{directive-name} Optional Title :option: value Content here ::: Used for: Cards, tabs, buttons, steps, list-table Nesting with Named Closers Bengal supports named closers to avoid fence-counting when nesting directives. Use :::{/name} to explicitly close a directive: Basic Nesting (container with items): 1 2 3 4 5 6 7 8 9 10 11 12:::{cards} :columns: 3 :::{card} Card Title Card content here ::: :::{card} Card Title 2 More content ::: :::{/cards} Deep Nesting (admonitions within steps, tabs within cards, etc.): 1 2 3 4 5 6 7 8 9 10 11 12 13:::{steps} :::{step} First Step :::{tip} Remember to check the logs! ::: :::{/step} :::{step} Second Step More content :::{/step} :::{/steps} Rule: Use :::{/directive-name} to close any container directive. This eliminates the need to count colons. Categories Admonitions Reference for admonition directives (note, warning, tip, danger, etc.) Layout Directives Reference for layout directives (cards, tabs, dropdown, grid) Formatting Directives Reference for formatting directives (badge, button, steps, checklist, rubric, list-table) Interactive Directives Reference for interactive directives (code-tabs, data-table) Content Reuse Directives Reference for content reuse directives (include, literalinclude) Media Directives Reference for media embed directives (YouTube, Vimeo, video, audio, figure, code playgrounds, terminal recordings) Navigation Directives Reference for navigation directives (child-cards, breadcrumbs, siblings, prev-next, related) 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 1 2 3:::{note} This is a note with **markdown** support. ::: Card Grid 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15:::{cards} :columns: 3 :::{card} Card 1 :icon: book :link: /docs/ Content here ::: :::{card} Card 2 Content here ::: :::{/cards} Tabs 1 2 3 4 5:::{tab-set} :::{tab-item} Python ```python print("Hello") ::: 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 ```markdown :::{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 Basic Usage - Show terms tagged with "directives": 1 2 3:::{glossary} :tags: directives ::: Progressive Disclosure - Show first 3 terms, rest expandable: 1 2 3 4:::{glossary} :tags: directives, core :limit: 3 ::: Fully Collapsed - Entire glossary in collapsible section: 1 2 3 4:::{glossary} :tags: formatting :collapsed: true ::: Both Options - Collapsed, with limited terms when expanded: 1 2 3 4 5:::{glossary} :tags: layout :collapsed: true :limit: 2 ::: Glossary Data Format Terms are defined in data/glossary.yaml: 1 2 3 4 5 6 7 8terms: - 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 -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 1490 - Reading Time: 7 minutes