# Interactive Elements URL: /bengal/docs/0.5.0/content/authoring/interactive/ Section: authoring -------------------------------------------------------------------------------- Interactive Elements How to create engaging, interactive documentation. Tabs Present related content in switchable tabs: ::::{tab-set} :::{tab-item} macOS ```bash brew install bengal ``` ::: :::{tab-item} Linux ```bash pip install bengal ``` ::: :::{tab-item} Windows ```powershell pip install bengal ``` ::: :::: macOS Linux Windows brew install bengal pip install bengal pip install bengal When to Use Tabs Platform-specific instructions (macOS/Linux/Windows) Language alternatives (Python/JavaScript/Go) Framework variations (React/Vue/Svelte) Configuration formats (YAML/TOML/JSON) Tip Tip Tabs remember the user's selection across pages. If someone picks "macOS", they'll see macOS content on other tabbed sections too. Code Tabs For multi-language code examples, use code-tabs — tab labels are derived directly from code fence languages: Code Python Code JavaScript Terminal Bash Copy Copy import requests response = requests.get("https://api.example.com/users") users = response.json() Copy Copy const response = await fetch("https://api.example.com/users"); const users = await response.json(); Copy Copy curl -X GET "https://api.example.com/users" \ -H "Authorization: Bearer $TOKEN" Key differences from tab-set: Simpler syntax: Just code fences, no markers or nested directives Auto language sync: All code-tabs on the page switch together Built-in features: Language icons, copy button, line numbers Zero config: Smart defaults for code-first documentation See Code Blocks for more options like filenames, custom labels, and line highlighting. Dropdowns Hide optional or detailed content: :::{dropdown} Advanced Configuration :icon: settings Here's the full configuration reference... ::: Settings Advanced Configuration Here's where advanced configuration details would go... Dropdown Options Option Description :open: Start expanded :icon: Icon name (from icon library) :description: Secondary text below the title :color: Color variant: success, warning, danger, info, minimal :class: CSS class for styling Dropdown Use Cases FAQ answers Advanced options Troubleshooting details Long code examples Optional explanations Step-by-Step Guides Create visual step sequences: :::{steps} :::{step} Install Dependencies :description: Set up your development environment :duration: 5 min ```bash pip install bengal ``` :::{/step} :::{step} Create Your Site :description: Initialize a new Bengal project ```bash bengal new site mysite cd mysite ``` :::{/step} :::{step} Start the Server :description: Preview your site locally ```bash bengal serve ``` Visit http://localhost:5173 to see your site. :::{/step} :::{/steps} Step Options Option Description :description: Brief description shown below title :duration: Estimated time (e.g., "5 min") :optional: Mark step as optional Cards Create visual navigation or feature highlights: :::{cards} :columns: 3 :::{card} Getting Started :icon: rocket :link: docs/get-started New to Bengal? Start here. :::{/card} :::{card} Tutorials :icon: book :link: docs/tutorials Learn by building. :::{/card} :::{card} Reference :icon: list :link: docs/reference Complete API docs. :::{/card} :::{/cards} Card Options Option Description :columns: Number of columns (1-4) :gap: Gap size: small, medium, large Individual Card Options Option Description :icon: Icon name :link: Click destination :badge: Badge text :color: Card accent color Auto-Generated Cards Generate cards from child pages: :::{child-cards} :columns: 2 ::: This automatically creates cards for all pages in the current section. Buttons Add call-to-action buttons. The URL goes in the directive title, and the button text goes in the content: :::{button} /docs/get-started/ :color: primary Get Started ::: :::{button} https://github.com/example/repo :color: secondary :icon: github :target: _blank View on GitHub ::: Button Options Option Description :color: primary, secondary, success, warning, danger, info, light, dark :style: default, pill (fully rounded), outline :size: small, medium, large :icon: Icon name :target: Link target (e.g., _blank for external links) Checklists Interactive task lists with optional progress tracking: :::{checklist} Deployment Checklist :show-progress: - [x] Run tests locally - [x] Update version number - [ ] Create changelog entry - [ ] Tag the release - [ ] Deploy to staging - [ ] Verify staging - [ ] Deploy to production ::: Deployment Checklist 2/7 complete Run tests locally Update version number Create changelog entry Tag the release Deploy to staging Verify staging Deploy to production (function() { const checklist = document.currentScript.closest('.checklist'); if (!checklist) return; const progressBar = checklist.querySelector('.checklist-progress-bar'); const progressText = checklist.querySelector('.checklist-progress-text'); const checkboxes = checklist.querySelectorAll('input[type="checkbox"]'); if (!progressBar || !progressText || !checkboxes.length) return; function updateProgress() { const total = checkboxes.length; const checked = Array.from(checkboxes).filter(cb => cb.checked).length; const percentage = Math.round((checked / total) * 100); progressBar.style.width = percentage + '%'; progressText.textContent = checked + '/' + total; } checkboxes.forEach(function(checkbox) { checkbox.addEventListener('change', updateProgress); }); })(); Checklist Options Option Description :style: default, numbered, minimal :show-progress: Display completion percentage bar :compact: Tighter spacing between items Combining Elements Create rich, interactive content by combining elements: ::::{steps} :::{step} Choose Your Platform :description: Select installation method :::{tab-set} :::{tab-item} pip ```bash pip install bengal ``` :::{/tab-item} :::{tab-item} pipx ```bash pipx install bengal ``` :::{/tab-item} :::{/tab-set} :::{/step} :::{step} Verify Installation ```bash bengal --version ``` :::{dropdown} Troubleshooting :icon: alert If you see "command not found", ensure Python's bin directory is in your PATH. ::: :::{/step} ::::{/steps} Best Practices Use tabs for platform/language alternatives Use dropdowns for optional details Use steps for sequential procedures Use cards for navigation or feature lists Don't over-nest interactive elements Ensure content works without JavaScript Accessibility All interactive elements are keyboard-navigable: Tabs: Arrow keys to switch, Enter to select Dropdowns: Enter/Space to toggle Cards: Tab to focus, Enter to follow link Info Seealso Interactive Directives Reference — Complete options Layout Directives — Cards and grids Navigation Directives — Breadcrumbs, prev/next -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 835 - Reading Time: 4 minutes