# Formatting Directives URL: /docs/reference/directives/formatting/ Section: directives Tags: reference, directives, formatting, badge, button, steps -------------------------------------------------------------------------------- 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. 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., _blank for 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 Badges: Use for labels, tags, or status indicators Buttons: Use for primary calls-to-action Steps: Use for sequential instructions or tutorials Checklists: Use for prerequisites, requirements, or task lists Rubrics: Use for API documentation section labels 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 -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 974 - Reading Time: 5 minutes