# Tables

URL: /docs/content/authoring/tables/
Section: authoring

--------------------------------------------------------------------------------

Tables Bengal supports three table formats, each suited to different use cases. Quick Reference Format Best For Features Pipe tables Simple data, 3-5 columns Standard Markdown, easy to write list-table Complex cells, multi-line content Code blocks, lists, formatted text data-table Large datasets (50+ rows) Sort, filter, search, pagination Pipe Tables (Standard Markdown) Use pipe tables for simple, scannable data: | Name | Role | Location | |------|------|----------| | Alice | Engineer | NYC | | Bob | Designer | LA | | Carol | PM | Seattle | Result: Name Role Location Alice Engineer NYC Bob Designer LA Carol PM Seattle Column Alignment Control alignment with colons in the separator row: | Left | Center | Right | |:-----|:------:|------:| | Text | Text | 99.99 | | More | More | 0.50 | 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 has no rowsList-Table Options Option Description Example :header-rows: Number of header rows (default: 0) :header-rows: 1 :widths: Column widths as percentages :widths: 30 70 :class: CSS class for styling :class: striped 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 Option Description Default :search: Enable text search false :filter: Enable column filters false :sort: Enable column sorting false :pagination: Rows per page 25 :columns: Columns to display (comma-separated) All columns :height: Fixed table height Auto 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 Scenario Use This Simple data, few columns Pipe table Code examples in cells list-table Multi-paragraph cells list-table Feature comparison list-table with :header-rows: 1 API reference tables list-table with code cells Hardware/software matrices data-table Datasets with 50+ rows data-table User-searchable data data-table with :search: true 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: Use list-table for cells containing code blocks. Pipe tables don't support fenced code. Data-Table Not Loading Problem: data-table shows error or empty. Fix: Verify the data file path is correct (relative to content root) Check YAML/CSV syntax is valid Ensure column names in :columns: match the data file Best Practices Use pipe tables for simple, scannable data Use list-table when cells need rich formatting Always include a header row for context Keep tables focused—one topic per table Consider mobile readers—avoid very wide tables Use :widths: to control column proportions Right-align numeric columns for easier scanning See Also Formatting Directives Reference — Complete directive options Authoring Overview — Other content authoring features

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 717
- Reading Time: 4 minutes