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.

Quick Reference

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

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

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 indata/glossary.yaml:

1
2
3
4
5
6
7
8

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 forcode,**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