sphinx-filter-tabs: Accessible Filters

Welcome to the official documentation for sphinx-filter-tabs.

This Sphinx extension provides a robust, accessible, and JavaScript-free way to create filterable content tabs. It’s ideal for documentation that needs to present information for different contexts, such as programming languages, operating systems, or installation methods.

Key Features:

  • No JavaScript: The filtering is achieved with pure CSS for speed and compatibility.

  • Accessible: Follows WAI-ARIA best practices for keyboard navigation and screen readers.

  • Customizable: Easily theme colors and styles directly from your conf.py.

  • Graceful Fallback: Renders as simple admonitions in non-HTML outputs like PDF/LaTeX.

You can find the project’s source code on the GitHub repository. You can also download this documentation as a PDF file.

Installation

Install the extension using pip:

pip install sphinx-filter-tabs

Then, add it to your Sphinx project’s conf.py file:

extensions = [
    'filter_tabs.extension',
]

Usage Example

Here is a live demonstration of the extension.

Filter by: Python, C++, JavaScript

This is general content visible regardless of the selected filter. It’s perfect for introductory text or information that applies to all tabs.

This panel shows content specific to Python.

def hello_world():
    print("Hello from Python!")

This panel shows content specific to C++.

#include <iostream>

int main() {
    std::cout << "Hello from C++!" << std::endl;
    return 0;
}

This panel shows content specific to JavaScript.

function helloWorld() {
    console.log("Hello from JavaScript!");
}

Nested Tabs

You can nest filter-tabs directives to create more complex layouts. Simply indent the inner tab set within a tab directive of the outer set.

Filter by: Windows, macOS, Linux

This is the content for Windows. Here are some platform-specific installation instructions:

Filter by: Pip, Conda

Instructions for installing with Pip on Windows.

Instructions for installing with Conda on Windows.

This is the content for macOS.

This is the content for Linux.

Changelog

Version 0.8.0

  • Added keyboard navigation using tab and arrows

  • Allowed for nested tabs and included example usage

  • Refactor HTML generation according to WAI-ARIA recommendations

  • Extended README.md with build and test instructions for developers

Version 0.7.0

  • Fixed HTML errors

Version 0.6.0

  • Initial release