Formatting Directives

Formatting directives provide styled components for badges, buttons, step-by-step guides, and more.

Key Terms

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.

Badge

Create styled badges for labels, tags, or status indicators.

Aliases:bdg

Syntax:

:::{badge} Text
:class: badge-class
:::

Options:

Common badge classes:badge-primary, badge-secondary, badge-success, badge-danger, badge-warning, badge-info, badge-cli-command, api-badge

Examples

Example: Basic Badge

:::{badge} New
:::

Example: Custom Class

:::{badge} Deprecated
:class: badge-danger
:::

Example: CLI Command Badge

:::{badge} bengal build
:class: badge-cli-command
:::

Icon

Embed inline SVG icons from Bengal's built-in icon library.

Aliases:icon, svg-icon

Syntax:

:::{icon} terminal
:::

:::{icon} docs
:size: 16
:class: text-muted
:::

Options:

Icons are loaded from Bengal's theme assets. If an icon is not found, a placeholder is rendered.

Examples

Example: Basic Icon

:::{icon} home
:::

Example: Sized Icon

:::{icon} arrow-right
:size: 16
:::

Example: With Accessibility Label

:::{icon} external-link
:aria-label: Opens in new window
:::

Button

Create styled link buttons for calls-to-action.

Syntax:

:::{button} /path/to/page/
:color: primary
:style: pill
:size: large
:icon: rocket
:target: _blank

Button Text
:::

Options:

• :color: - Color: primary (default), secondary, success, danger, warning, info, light, dark
• :style: - Style: default (rounded), pill (fully rounded), outline
• :size: - Size: small, medium (default), large
• :icon:- Icon name (same as cards)
• :target: - Link target (e.g., _blankfor external links)

Examples

Example: Basic Button

:::{button} /docs/
Get Started
:::

Example: Primary CTA

:::{button} /signup/
:color: primary
:style: pill
:size: large

Sign Up Free
:::

Example: External Link

:::{button} https://github.com/yourproject
:color: secondary
:target: _blank

View on GitHub
:::

Steps

Create visual step-by-step guides using named closers for clean, readable syntax.

Steps Container ({steps})

Container for multiple steps. Use:::{/steps}to close.

Syntax:

:::{steps}
:class: custom-class
:style: compact
:start: 1

:::{step} Step Title
Step content with **markdown** support.
:::{/step}

:::{step} Next Step
More content
:::{/step}

:::{/steps}

Options:

Individual Step ({step})

Single step within a steps container. Use:::{/step}to close.

Syntax:

:::{step} Step Title
:class: custom-class
:description: Brief context before diving into the step content.
:duration: 5 min
:optional:

Step content with **markdown** and nested directives.
:::{/step}

Options:

Examples

Example: Basic Steps

:::{steps}

:::{step} Install Dependencies
```bash
pip install bengal
```
:::{/step}

:::{step} Create Site
```bash
bengal new mysite
```
:::{/step}

:::{step} Build Site
```bash
bengal build
```
:::{/step}

:::{/steps}

Example: Steps with Nested Admonitions

Named closers eliminate fence-counting for complex nesting:

:::{steps}

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

:::{step} Second Step
More content
:::{/step}

:::{/steps}

Note: Named closers (:::{/name}) explicitly close directives, making deeply nested content readable without counting colons.

Checklist

Create styled checklist containers for bullet lists and task lists with optional progress tracking.

Syntax:

:::{checklist} Optional Title
:style: numbered
:show-progress:
:compact:
- Item one
- Item two
- [x] Completed item
- [ ] Unchecked item
:::{/checklist}

Options:

Examples

Example: Basic Checklist

:::{checklist} Prerequisites
- Python 3.14+
- Git installed
- Text editor
:::{/checklist}

Example: Task List with Progress

:::{checklist} Setup Tasks
:show-progress:
- [x] Install dependencies
- [x] Configure site
- [ ] Deploy to production
:::{/checklist}

Example: Numbered Checklist

:::{checklist} Getting Started Steps
:style: numbered
- Create a new project
- Install dependencies
- Configure settings
:::{/checklist}

Rubric

Create pseudo-headings that look like headings but don't appear in the table of contents. Perfect for API documentation labels.

Syntax:

:::{rubric} Label Text
:class: custom-class
:::

Options:

• :class:- Custom CSS class

Note: Rubrics don't contain content - they're label-only directives. Content after the rubric is separate markdown.

Examples

Example: API Documentation

:::{rubric} Parameters
:class: rubric-parameters
:::

- `param1` (str): First parameter
- `param2` (int): Second parameter

:::{rubric} Returns
:class: rubric-returns
:::

Returns a dictionary with results.

List Table

Create tables from nested lists (avoids pipe character issues in type annotations).

Syntax:

:::{list-table}
:header-rows: 1
:widths: 20 30 50
:class: custom-class

* - Header 1
  - Header 2
  - Header 3
* - Row 1, Col 1
  - Row 1, Col 2
  - Row 1, Col 3
* - Row 2, Col 1
  - Row 2, Col 2
  - Row 2, Col 3
:::

Options:

• :header-rows:- Number of header rows (default: 0)
• :widths:- Space-separated column widths (percentages)
• :class:- CSS class

Examples

Example: Basic Table

:::{list-table}
:header-rows: 1

* - Name
  - Type
  - Description
* - `name`
  - `str`
  - User name
* - `age`
  - `int`
  - User age
:::

Example: With Column Widths

:::{list-table}
:header-rows: 1
:widths: 20 30 50

* - Column 1
  - Column 2
  - Column 3
* - Data 1
  - Data 2
  - Data 3
:::

Best Practices

1. Badges: Use for labels, tags, or status indicators
2. Buttons: Use for primary calls-to-action
3. Steps: Use for sequential instructions or tutorials
4. Checklists: Use for prerequisites, requirements, or task lists
5. Rubrics: Use for API documentation section labels
6. List Tables: Use when pipe characters conflict with code syntax

Related

• Icon Reference - SVG icons for content and templates
• Layout Directives - Cards, tabs, dropdowns
• Admonitions - Callout boxes