Interactive Directives

Interactive directives provide JavaScript-enhanced components for code examples and data tables.

Quick Reference

Key Terms

Code Tabs

An interactive tabbed interface ({code-tabs}) for displaying code examples in multiple languages. Users can switch between languages with tab navigation.

Data Table

An interactive table directive ({data-table}) with JavaScript-enhanced features like sorting, filtering, and pagination. Requires Tabulator.js in your theme.

Code Tabs

Create tabbed interfaces for multi-language code examples with automatic language sync, syntax highlighting, and copy buttons.

Aliases:{code-tabs}, {code_tabs}

Features

• Simplified syntax — Tab labels derived from code fence language (no markers needed)
• Auto language sync — All code-tabs on a page sync when user picks a language
• Language icons — Automatic icons for common language categories
• Pygments highlighting — Proper syntax coloring with line numbers and line emphasis
• Copy button — One-click copy per tab
• Filename display — Show filename badges in tab labels

Syntax

Tab labels are derived automatically from the code fence language:

:::{code-tabs}

```python main.py {3-4}
def greet(name):
    """Say hello."""
    print(f"Hello, {name}!")

greet("World")
```

```javascript index.js {2-3}
function greet(name) {
    // Say hello
    console.log(`Hello, ${name}!`);
}

greet("World");
```

:::

Info String Format

The code fence info string supports filename, title override, and highlights:

language [filename] [title="Label"] [{line-highlights}]

Options

Option aliases::line-numbers: = :linenos:

Custom Tab Labels

Usetitle="..."to override the default language-derived label:

:::{code-tabs}

```javascript title="React"
const [count, setCount] = useState(0);
```

```javascript title="Vue"
const count = ref(0);
```

:::

Files Without Extensions

For files likeDockerfile that have no extension, use title=:

:::{code-tabs}

```dockerfile title="Dockerfile"
FROM python:3.14-slim
```

```yaml docker-compose.yml
services:
  web:
    build: .
```

:::

Language Display Names

Languages are automatically formatted with proper casing:

Language Sync

By default, all code-tabs on a page with the same sync key synchronize. When a user selects Python in one code-tabs block, all other blocks switch to Python.

Sync is persistent: User preferences are saved to localStorage and restored on page load.

Disable sync for a specific block:

:::{code-tabs}
:sync: none

```python
# Before
```

```python
# After
```

:::

Custom sync groups:

:::{code-tabs}
:sync: api-examples

```python
...
```

:::

:::{code-tabs}
:sync: config-examples

```yaml
...
```

:::

Examples

Example: Basic Usage

:::{code-tabs}

```python
def hello():
    print("Hello, World!")
```

```javascript
function hello() {
    console.log("Hello, World!");
}
```

:::

Example: With Filenames and Highlights

:::{code-tabs}

```python api_client.py {3-4}
import requests

def get_users():
    response = requests.get("/api/users")
    return response.json()
```

```javascript client.js {3-4}
import fetch from 'node-fetch';

async function getUsers() {
    const response = await fetch('/api/users');
    return response.json();
}
```

:::

Example: Multiple Languages

:::{code-tabs}

```python
print("Hello")
```

```javascript
console.log("Hello");
```

```go
fmt.Println("Hello")
```

```bash
echo "Hello"
```

:::

Rendering

Code tabs render as an interactive tabbed interface with:

• Tab navigation for switching languages
• Language icons (terminal for bash/shell, database for SQL, code for others)
• Filename badges in tab labels
• Pygments syntax highlighting with line numbers
• Line emphasis for highlighted lines
• Copy button on hover
• First tab selected by default
• Synced tab selection across the page

Language Icons

Icons are automatically assigned based on language category:

Legacy Syntax

The older### Languagemarker syntax is still supported for backward compatibility:

:::{code-tabs}

### Python (main.py)
```python
print("hello")
```

### JavaScript
```javascript
console.log("hello");
```

:::

This legacy syntax is not recommended for new content.

Data Table

Create interactive data tables with sorting, filtering, and pagination from external data files.

Requires: Tabulator.js (included in default theme)

Syntax

The directive takes a file path argument pointing to a YAML or CSV data file:

```{data-table} data/people.yaml
:search: true
:filter: true
:sort: true
:pagination: 50
```

Supported File Formats

YAML (recommended):

# data/people.yaml
columns:
  - title: Name
    field: name
  - title: Age
    field: age
  - title: City
    field: city
data:
  - name: Alice
    age: 30
    city: Seattle
  - name: Bob
    age: 25
    city: Portland

CSV:

name,age,city
Alice,30,Seattle
Bob,25,Portland

Column headers are auto-generated from field names in CSV files.

Options

Examples

Example: Basic Data Table

```{data-table} data/api-functions.yaml
```

With data/api-functions.yaml:

columns:
  - title: Name
    field: name
  - title: Type
    field: type
  - title: Description
    field: description
data:
  - name: get_user
    type: Function
    description: Get user by ID
  - name: create_user
    type: Function
    description: Create new user
  - name: update_user
    type: Function
    description: Update user

Example: With Options

```{data-table} data/packages.yaml
:search: true
:filter: true
:sort: true
:pagination: false
:height: 300px
```

Example: Filtered Columns

Show only specific columns from the data file:

```{data-table} data/people.yaml
:columns: name,city
```

Rendering

Data tables render as interactive Tabulator tables with:

• Search box: Filter across all columns (if:search: true)
• Column filters: Per-column filtering in headers (if:filter: true)
• Sorting: Click headers to sort (if:sort: true)
• Pagination: Navigate large datasets (if:pagination:is a number)
• Responsive design: Columns collapse on narrow screens
• Keyboard navigation: Full keyboard support for accessibility

Best Practices

1. Code Tabs: Use for comparing code across languages or showing multiple approaches
2. Language Sync: Keep sync enabled (default) for API docs with consistent language examples
3. Filenames: Add filenames when showing complete file contents
4. Line Highlights: Use sparingly to draw attention to key lines
5. Data Tables: Use YAML format for explicit column definitions; CSV for simple tabular data
6. Performance: Enable pagination for tables with more than 50 rows
7. Accessibility: Both directives support full keyboard navigation

Related

• Layout Directives — Static tabs (tab-set) and cards
• Formatting Directives — List tables (static)
• Code Blocks — Standard code block syntax