Tables

Bengal supports three table formats, each suited to different use cases.

Quick Reference

Pipe Tables (Standard Markdown)

Use pipe tables for simple, scannable data:

| Name | Role | Location |
|------|------|----------|
| Alice | Engineer | NYC |
| Bob | Designer | LA |
| Carol | PM | Seattle |

Result:

Column Alignment

Control alignment with colons in the separator row:

| Left | Center | Right |
|:-----|:------:|------:|
| Text | Text   | 99.99 |
| More | More   | 0.50  |

• :---left-align (default)
• :--:center
• ---:right-align

List-Table Directive

For tables with multi-line cells, code blocks, or nested content:

:::{list-table} Pricing Comparison
:header-rows: 1
:widths: 20 40 40

* - Feature
  - Free Plan
  - Pro Plan
* - Storage
  - 5 GB
  - Unlimited
* - Support
  - Community forums
  - Priority email + phone
* - API Access
  - 1,000 calls/month
  - Unlimited
:::

Result:

List-Table Options

Rich Content in Cells

List-table cells support full Markdown, including code blocks:

:::{list-table} API Endpoints
:header-rows: 1

* - Endpoint
  - Description
  - Response
* - `GET /users`
  - List all users.

    Returns paginated results with metadata.
  - ```json
    {"users": [...], "total": 100}
    ```
* - `POST /users`
  - Create a new user.

    Requires authentication.
  - ```json
    {"id": "abc123", "name": "Alice"}
    ```
:::

Key syntax:

• Start each row with* -
• Start each subsequent cell with -(2-space indent)
• Blank line before multi-line content within a cell

Data-Table Directive

For large datasets with interactive features:

:::{data-table} data/products.yaml
:search: true
:filter: true
:sort: true
:pagination: 10
:columns: name,price,category
:::

Data-Table Options

Data File Format

Data files can be YAML or CSV:

# data/products.yaml
- name: Widget A
  price: 29.99
  category: Electronics
  stock: 150
- name: Widget B
  price: 49.99
  category: Electronics
  stock: 75
- name: Gadget C
  price: 19.99
  category: Accessories
  stock: 200

Or CSV format:

name,price,category,stock
Widget A,29.99,Electronics,150
Widget B,49.99,Electronics,75
Gadget C,19.99,Accessories,200

Choosing the Right Format

Styling Tables

CSS Classes

Add custom classes to list-tables:

:::{list-table}
:class: striped hover compact

* - Row 1
  - Data
* - Row 2
  - Data
:::

Common classes: striped, hover, compact, bordered

Responsive Behavior

Tables scroll horizontally on small screens. For wide tables:

• Split into multiple focused tables
• Move less critical columns to expandable sections
• Provide downloadable CSV for full data

Troubleshooting

Cells Not Aligning

Problem: Content appears in wrong columns.

Fix: Ensure consistent indentation. Each cell must start with exactly -(2 spaces + hyphen):

* - First cell
  - Second cell    ✅ Correct (2 spaces)
   - Third cell    ❌ Wrong (3 spaces)

Code Blocks Breaking Table

Problem: Fenced code blocks inside pipe tables break rendering.

Fix: Uselist-tablefor cells containing code blocks. Pipe tables don't support fenced code.

Data-Table Not Loading

Problem:data-tableshows error or empty.

Fix:

1. Verify the data file path is correct (relative to content root)
2. Check YAML/CSV syntax is valid
3. Ensure column names in:columns:match the data file

Best Practices

See Also

• Formatting Directives Reference — Complete directive options
• Authoring Overview — Other content authoring features