Formatting Directives

Reference for formatting directives (badge, button, steps, checklist, rubric, list-table)

4 min read 781 words

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.

Syntax:

1
2
3
:::{badge} Text
:class: badge-class
:::

Options:

  • :class:- CSS classes (default:badge badge-secondary)

Alias:{bdg}(Sphinx-Design compatibility)

Examples

Basic Badge:

1
2
:::{badge} New
:::

Custom Class:

1
2
3
:::{badge} Deprecated
:class: badge-danger
:::

CLI Command Badge:

1
2
3
:::{badge} bengal build
:class: badge-cli-command
:::

Button

Create styled link buttons for calls-to-action.

Syntax:

1
2
3
4
5
6
7
8
9
:::{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

Basic Button:

1
2
3
:::{button} /docs/
Get Started
:::

Primary CTA:

1
2
3
4
5
6
7
:::{button} /signup/
:color: primary
:style: pill
:size: large

Sign Up Free
:::

External Link:

1
2
3
4
5
6
:::{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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
:::{steps}
:class: custom-class
:style: compact

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

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

:::{/steps}

Options:

  • :class:- Custom CSS class
  • :style:- Style:default,compact

Individual Step ({step})

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

Syntax:

1
2
3
4
5
:::{step} Optional Title
:class: custom-class

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

Options:

  • :class:- Custom CSS class

Examples

Basic Steps:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
:::{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}

Steps with Nested Admonitions:

Named closers eliminate fence-counting for complex nesting:

 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}

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.

Syntax:

1
2
3
4
5
6
:::{checklist} Optional Title
- Item one
- Item two
- [x] Completed item
- [ ] Unchecked item
:::

Options:

  • Title (optional) - Checklist title

Examples

Basic Checklist:

1
2
3
4
5
:::{checklist} Prerequisites
- Python 3.10+
- Git installed
- Text editor
:::

Task List:

1
2
3
4
5
:::{checklist} Setup Tasks
- [x] Install dependencies
- [x] Configure site
- [ ] Deploy to production
:::

Rubric

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

Syntax:

1
2
3
:::{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

API Documentation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
:::{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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
:::{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

Basic Table:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
:::{list-table}
:header-rows: 1

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

With Column Widths:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
:::{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