Tables & Lists

Material for MkDocs provides enhanced support for tables and lists, including sorting, filtering, and advanced formatting options.

Tables

Basic Tables

Standard Markdown tables with enhanced styling:

Feature	Description	Status
Tables	Enhanced table styling	✅ Stable
Sorting	Client-side sorting	✅ Stable
Filtering	Search within tables	🚧 Beta
Responsive	Mobile-friendly tables	✅ Stable

Alignment

Control column alignment:

Left Aligned	Center Aligned	Right Aligned
Content	Content	Content
Left	Center	Right
Lorem ipsum	dolor sit	amet

| Left Aligned | Center Aligned | Right Aligned |
|:------------|:--------------:|--------------:|
| Content | Content | Content |

Complex Tables

Tables with various content types:

Component	Version	Size	Dependencies	Status
mkdocs	1.5.3	3.2 MB	Python 3.8+
material	9.5.0	8.1 MB	MkDocs 1.5+
jupyter	0.24.0	1.5 MB	Jupyter

Data Tables

Configuration data in tables:

Parameter	Type	Default	Description
site_name	string	Required	The name of your documentation site
site_url	string	null	The canonical URL of your site
repo_url	string	null	Repository URL for edit links
theme.name	string	mkdocs	Theme to use for documentation
theme.palette.primary	string	indigo	Primary color for Material theme

Responsive Tables

For wide tables, enable horizontal scrolling:

ID	Name	Email	Department	Position	Start Date	Salary	Status
001	John Doe	john.doe@example.com	Engineering	Senior Developer	2020-01-15	$120,000	Active
002	Jane Smith	jane.smith@example.com	Marketing	Marketing Manager	2019-06-20	$95,000	Active
003	Bob Johnson	bob.johnson@example.com	Sales	Sales Representative	2021-03-10	$75,000	Active

Sortable Tables

Configuration

Enable table sorting with Tablesort:

<!-- docs/overrides/main.html -->
{% extends "base.html" %}

{% block libs %}
  {{ super() }}
  <script src="https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js"></script>
  <script>
    document.addEventListener('DOMContentLoaded', function() {
      const tables = document.querySelectorAll("article table:not([class])");
      tables.forEach(table => new Tablesort(table));
    });
  </script>
{% endblock %}

Sortable Example

Click headers to sort:

Language	Popularity	Trend	Type
Python	85%	↑ Rising	Interpreted
JavaScript	79%	→ Stable	Interpreted
Go	65%	↑ Rising	Compiled
Rust	45%	↑ Rising	Compiled
PHP	40%	↓ Declining	Interpreted

Lists

Unordered Lists

Basic unordered list:

• First level item
• Another first level item
• Second level item
• Another second level item
  • Third level item
  • Another third level item
• Back to first level

Ordered Lists

Numbered lists with sub-items:

1. First step
2. Second step
3. Sub-step A
4. Sub-step B
5. Third step
6. Sub-step A
   1. Detail 1
   2. Detail 2
7. Sub-step B

Task Lists

Interactive checkboxes:

• Create project structure
• Install dependencies
• Write documentation
• Setup guide
• API reference
• Examples
• Add tests
• Deploy

- [x] Completed task
- [ ] Incomplete task

Definition Lists

Term definitions:

MkDocs

A fast, simple static site generator geared towards building project documentation.

Material for MkDocs

A Material Design theme for MkDocs with tons of features and customization options.

Includes over 60 customizations and extensions.

Python

A high-level programming language.

Known for its simplicity and readability.

Used in web development, data science, and more.

Mixed Lists

Combining different list types:

1. Setup Phase
2. Install Python 3.8+
3. Install pip

4. Create virtual environment

   python -m venv venv
   source venv/bin/activate
   

5. Installation

6. Core dependencies:
   1. MkDocs: pip install mkdocs
   2. Material: pip install mkdocs-material

7. Optional extensions:

   • mkdocs-jupyter
   • mkdocstrings
   • mkdocs-git-revision-date

8. Configuration

9. Create mkdocs.yml
10. Set theme to material
11. Configure plugins

Advanced Formatting

Tables with Lists

Combining tables and lists:

Feature	Requirements	Benefits
Search	• Enabled by default • No configuration	• Instant results • Keyboard shortcuts • Highlighting
Navigation	• Theme feature • YAML config	1. Better UX 2. Faster browsing 3. Clear structure
Code Blocks	Requirements: - Pygments - pymdownx.highlight	✓ Syntax highlighting ✓ Line numbers ✓ Copy button

Nested Tables

Tables within lists:

1. Database Comparison

Database	Type	Use Case
PostgreSQL	Relational	Complex queries
MongoDB	NoSQL	Flexible schema
Redis	Key-Value	Caching

1. Performance Metrics

Metric	PostgreSQL	MongoDB	Redis
Read Speed	Fast	Very Fast	Ultra Fast
Write Speed	Moderate	Fast	Ultra Fast
Query Complexity	High	Moderate	Low

Styled Lists

Custom styled lists with CSS:

• Completed successfully
• Warning - needs review
• Failed - action required
• Informational note

Styling

Custom CSS

/* docs/assets/stylesheets/tables-lists.css */

/* Striped tables */
.md-typeset table:not([class]) tbody tr:nth-child(odd) {
  background-color: var(--md-default-bg-color--lightest);
}

/* Hover effect */
.md-typeset table:not([class]) tbody tr:hover {
  background-color: var(--md-primary-fg-color--transparent);
}

/* Responsive wrapper */
.table-wrapper {
  overflow-x: auto;
  margin: 0 -1rem;
  padding: 0 1rem;
}

/* Custom list styles */
.custom-list ul {
  list-style: none;
  padding-left: 0;
}

.custom-list li {
  padding-left: 2em;
  position: relative;
}

.custom-list li .twemoji {
  position: absolute;
  left: 0;
  top: 0.1em;
}

/* Task list styling */
.md-typeset .task-list-item {
  list-style-type: none;
  margin-left: -1.5em;
}

.md-typeset .task-list-item input[type="checkbox"] {
  margin-right: 0.5em;
}

/* Definition list styling */
.md-typeset dl dt {
  font-weight: 700;
  margin-top: 1em;
}

.md-typeset dl dd {
  margin-left: 2em;
  margin-bottom: 0.5em;
}

Table Classes

Apply custom classes to tables:

Column 1	Column 2	Column 3
Data	Data	Data
{: .custom-table .striped }

| Column 1 | Column 2 |
|----------|----------|
| Data | Data |
{: .custom-table }

JavaScript Enhancements

Filterable Tables

Add search functionality to tables:

// Table filter function
function addTableFilter(tableId) {
  const input = document.createElement('input');
  input.type = 'text';
  input.placeholder = 'Filter table...';
  input.className = 'table-filter';

  const table = document.getElementById(tableId);
  table.parentNode.insertBefore(input, table);

  input.addEventListener('keyup', function() {
    const filter = this.value.toLowerCase();
    const rows = table.querySelectorAll('tbody tr');

    rows.forEach(row => {
      const text = row.textContent.toLowerCase();
      row.style.display = text.includes(filter) ? '' : 'none';
    });
  });
}

Dynamic Lists

Create interactive lists:

// Collapsible list items
document.querySelectorAll('.collapsible-list > li').forEach(item => {
  const toggle = document.createElement('span');
  toggle.className = 'toggle';
  toggle.textContent = '▶';

  item.insertBefore(toggle, item.firstChild);

  toggle.addEventListener('click', function() {
    const sublist = item.querySelector('ul, ol');
    if (sublist) {
      sublist.classList.toggle('collapsed');
      this.textContent = sublist.classList.contains('collapsed') ? '▶' : '▼';
    }
  });
});

Best Practices

Tables

1. Keep it simple: Avoid overly complex tables
2. Use headers: Always include column headers
3. Responsive design: Test on mobile devices
4. Consistent alignment: Use the same alignment style
5. Meaningful data: Ensure data is relevant and organized

Lists

1. Logical hierarchy: Maintain clear parent-child relationships
2. Consistent markers: Use the same list style throughout
3. Concise items: Keep list items brief and scannable
4. Proper nesting: Indent nested lists correctly
5. Task lists sparingly: Only for actual tasks

Accessibility

Table Accessibility

<table role="table">
  <caption>Sales Data for Q4 2023</caption>
  <thead>
    <tr>
      <th scope="col">Product</th>
      <th scope="col">Units Sold</th>
      <th scope="col">Revenue</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Widget A</th>
      <td>1,234</td>
      <td>$12,340</td>
    </tr>
  </tbody>
</table>

List Accessibility

• Use semantic HTML (<ul>, <ol>, <dl>)
• Provide context for screen readers
• Ensure keyboard navigation works
• Test with assistive technologies

Examples

Pricing Table

Plan	Price/Month	Features	Support	Action
Free	$0	• 1 User • 10 Projects • Basic Features	Community	Sign Up
Pro	$29	• 5 Users • Unlimited Projects • Advanced Features	Email	Start Trial
Enterprise	Custom	• Unlimited Users • All Features • Custom Integration	24/7 Phone	Contact Sales

Comparison List

Framework Comparison:

• React
• ✅ Large ecosystem
• ✅ Virtual DOM
• ✅ Component-based
• ❌ Learning curve

• ❌ Boilerplate code

• Vue

• ✅ Easy to learn
• ✅ Great documentation
• ✅ Reactive data
• ❌ Smaller ecosystem

• ❌ Less enterprise adoption

• Angular

• ✅ Full framework
• ✅ TypeScript support
• ✅ Enterprise ready
• ❌ Complexity
• ❌ Bundle size

See Also

• Markdown Tables
• Material Design - Data Tables
• MDN - HTML Tables
• W3C - Lists