# Formatting Directives URL: /bengal/docs/0.4.3/reference/directives/formatting/ Section: directives Tags: reference, directives, formatting, badge, icon, 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. Aliases: bdg Note Note Bengal also supports inline badge syntax: {bdg-primary}text`` for embedding badges within paragraphs. Syntax: :::{badge} Text :class: badge-class ::: Options: Option Default Description :class: badge badge-secondary CSS classes for the badge 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: Option Default Description :size: 24 Icon size in pixels :class: — Additional CSS classes :aria-label: — Accessibility label (uses icon name if omitted) 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 ::: Note Note Icons are resolved from theme assets in this order: site → theme → parent theme → default. Available icons include terminal, docs, bengal-rosette, and any custom icons in your theme's assets/icons/ directory. 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., _blank for 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: Option Default Description :class: — Custom CSS class for the container :style: default Visual style: default, compact :start: 1 Start numbering from this value 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: Option Default Description :class: — Custom CSS class for the step :description: — Lead-in text rendered before main content :optional: false Mark step as optional/skippable :duration: — Estimated time (e.g., "5 min", "1 hour") 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: Option Default Description Title — Optional title shown above the list :style: default Visual style: default, numbered, minimal :show-progress: false Display completion percentage for task lists :compact: false Tighter spacing between items :class: — Additional CSS classes 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 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: 1124 - Reading Time: 6 minutes