Interactive Elements

Create tabs, dropdowns, steps, and other interactive content

5 min read 953 words

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
```
:::
::::

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

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, usecode-tabs— tab labels are derived directly from code fence languages:

I0:

Key differences fromtab-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.

Hide optional or detailed content:

:::{dropdown} Advanced Configuration
:icon: settings

Here's the full configuration reference...
:::
Advanced Configuration

Here's where advanced configuration details would go...

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
  • 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.,_blankfor 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

  • Run tests locally
  • Update version number
  • Create changelog entry
  • Tag the release
  • Deploy to staging
  • Verify staging
  • Deploy to production

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

Seealso