Content Tabs

Content tabs allow you to organize related content into a tabbed interface, perfect for showing alternatives, platform-specific instructions, or different approaches to the same topic.

Overview

Content tabs provide:

• Grouped content - Organize related information
• Space efficiency - Multiple views in one location
• User choice - Let readers pick relevant content
• Synchronized tabs - Link tabs across the page
• Mobile friendly - Responsive tab interface
• Keyboard navigation - Full accessibility support

Configuration

Enable content tabs in mkdocs.yml:

markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true  # Required for Material theme
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

theme:
  features:
    - content.tabs.link  # Synchronize tab selection

Basic Usage

Simple Tabs

=== "Tab 1"

    This is the content of tab 1.

    It can contain any **Markdown** content.

=== "Tab 2"

    This is the content of tab 2.

    - Lists
    - Code blocks
    - Images
    - Anything!

Result:

Tab 1Tab 2

This is the content of tab 1.

It can contain any Markdown content.

This is the content of tab 2.

• Lists
• Code blocks
• Images
• Anything!

Code Examples

Common use case for showing code in different languages:

PythonJavaScriptJava

def greet(name):
    return f"Hello, {name}!"

# Usage
message = greet("World")
print(message)

function greet(name) {
    return `Hello, ${name}!`;
}

// Usage
const message = greet("World");
console.log(message);

public class Greeting {
    public static String greet(String name) {
        return "Hello, " + name + "!";
    }

    public static void main(String[] args) {
        String message = greet("World");
        System.out.println(message);
    }
}

Advanced Features

Linked Tabs

When content.tabs.link is enabled, tabs with the same label synchronize:

Installation Instructions:

npmyarnpnpm

npm install package-name

yarn add package-name

pnpm add package-name

Development Setup:

npmyarnpnpm

npm run dev

yarn dev

pnpm dev

Nested Content

Tabs can contain any content including other tabs:

FrontendBackend

ReactVue

function App() {
    return <h1>Hello React</h1>;
}

<template>
    <h1>Hello Vue</h1>
</template>

Node.jsPython

const express = require('express');
const app = express();

from flask import Flask
app = Flask(__name__)

Complex Content

OverviewInstallationConfiguration

Project Overview

This project demonstrates a full-stack application with:

• Modern frontend framework
• RESTful API backend
• Database integration
• Authentication system

Getting Started

Follow the installation guide in the next tab

Installation Guide

Prerequisites

• Node.js 16+
• Python 3.8+
• PostgreSQL 12+

Steps

1. Clone the repository
2. Install dependencies
3. Configure environment
4. Run migrations
5. Start development server

Configuration

Create a .env file:

DATABASE_URL=postgresql://localhost/myapp
SECRET_KEY=your-secret-key
API_URL=http://localhost:3000

Advanced Options

Option	Default	Description
DEBUG	false	Enable debug mode
LOG_LEVEL	info	Logging verbosity
CACHE_TTL	3600	Cache timeout

Use Cases

Platform-Specific Instructions

WindowsmacOSLinux

# Windows installation
choco install tool-name

# Add to PATH
$env:Path += ";C:\tools\tool-name"

# macOS installation
brew install tool-name

# Add to PATH
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc

# Linux installation
sudo apt-get install tool-name

# Add to PATH
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc

API Examples

cURLPythonJavaScript

curl -X GET https://api.example.com/users \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json"

import requests

response = requests.get(
    "https://api.example.com/users",
    headers={
        "Authorization": "Bearer TOKEN",
        "Content-Type": "application/json"
    }
)

const response = await fetch('https://api.example.com/users', {
    headers: {
        'Authorization': 'Bearer TOKEN',
        'Content-Type': 'application/json'
    }
});

Framework Comparisons

ReactVueAngular

Pros: - Large ecosystem - Flexible architecture - Strong community

Cons: - Steeper learning curve - Requires additional libraries

Pros: - Gentle learning curve - Great documentation - Built-in features

Cons: - Smaller ecosystem - Less job market demand

Pros: - Full framework - TypeScript first - Enterprise ready

Cons: - Complex for small projects - Verbose syntax

Styling

Custom CSS

/* docs/assets/stylesheets/tabs.css */

/* Tab container */
.md-typeset .tabbed-set {
  margin: 1em 0;
  border-radius: 0.2rem;
}

/* Tab labels */
.md-typeset .tabbed-labels {
  border-bottom: 2px solid var(--md-default-fg-color--lightest);
}

/* Active tab */
.md-typeset .tabbed-labels > label:checked {
  color: var(--md-accent-fg-color);
  border-bottom-color: var(--md-accent-fg-color);
}

/* Tab content */
.md-typeset .tabbed-content {
  padding: 1em 0;
}

/* Tab hover effect */
.md-typeset .tabbed-labels > label:hover {
  color: var(--md-accent-fg-color);
  cursor: pointer;
}

Icon Tabs

Add icons to tab labels:

Python JavaScript Java

Python implementation

JavaScript implementation

Java implementation

Best Practices

1. Meaningful Labels

Use clear, descriptive tab labels:

❌ Bad:
=== "1"
=== "2"
=== "3"

✅ Good:
=== "Installation"
=== "Configuration"
=== "Usage"

2. Consistent Organization

Keep similar content types together:

=== "Frontend Setup"
    Frontend instructions...

=== "Backend Setup"
    Backend instructions...

=== "Database Setup"
    Database instructions...

3. Limit Tab Count

Too many tabs can overwhelm:

• 2-5 tabs: Optimal
• 6-8 tabs: Maximum
• 9+ tabs: Consider restructuring

4. Mobile Considerations

Test on mobile devices: - Tabs scroll horizontally - Content remains readable - Touch targets are adequate

Accessibility

Keyboard Navigation

• Tab - Navigate to tab list
• Left / Right - Switch tabs
• Enter / Space - Select tab
• Screen reader announcements

ARIA Labels

Tabs include proper ARIA attributes: - role="tablist" - role="tab" - role="tabpanel" - aria-selected - aria-controls

Common Patterns

Installation Guide

PrerequisitesInstallConfigureRun

Before installing, ensure you have: - Node.js 16+ - Git - A code editor

git clone https://github.com/example/project
cd project
npm install

Create a .env file:

API_KEY=your-api-key
DATABASE_URL=your-database-url

npm start

API Documentation

RequestResponseErrors

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer TOKEN

{
  "name": "John Doe",
  "email": "john@example.com"
}

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Email is required"
  }
}

Integration

With Admonitions

InfoWarningDanger

Information

This is an informational message

Warning

This is a warning message

Danger

This is a danger message

With Code Annotations

Annotated Code

def process_data(data):
    result = []
    for item in data:  # (1)!
        if validate(item):  # (2)!
            result.append(transform(item))
    return result

1. Iterate through each item
2. Validate before processing

Troubleshooting

Tabs Not Rendering

1. Ensure alternate_style: true is set
2. Check indentation (4 spaces)
3. Verify empty lines between tab markers

Linked Tabs Not Working

1. Enable content.tabs.link feature
2. Ensure tab labels match exactly
3. Check for trailing spaces

Styling Issues

1. Clear browser cache
2. Verify CSS is loaded
3. Check for CSS conflicts

See Also

• PyMdown Extensions - Tabbed
• Material for MkDocs - Content Tabs
• Accessible Tabs Pattern