MkDocs Section Index Plugin

0.3.11 · active · verified Sat Apr 11

mkdocs-section-index is an MkDocs plugin that enables sections in your navigation to be clickable, leading to an index page rather than just expanding. This addresses a limitation in standard MkDocs where sections are typically not directly navigable pages. It is currently at version 0.3.11 and frequently releases updates to maintain compatibility with new versions of MkDocs and popular themes like MkDocs Material.

Warnings

breaking The maintainers have announced 'ProperDocs' as a community continuation of MkDocs, warning users when this plugin is used from the standard `mkdocs` executable. This signals a potential future fork or divergence in development and could impact long-term compatibility or maintenance if MkDocs and ProperDocs evolve separately.
Fix: Monitor announcements from both the mkdocs-section-index and ProperDocs projects for guidance on future compatibility and maintenance strategy.
gotcha The plugin frequently requires updates to maintain compatibility with specific versions of the MkDocs Material theme and MkDocs itself. Users should ensure their `mkdocs-section-index` version is compatible with their MkDocs and Material theme versions to avoid rendering issues.
Fix: Refer to the plugin's release notes and the MkDocs Material changelog when upgrading either the theme or MkDocs core to identify required `mkdocs-section-index` versions. Update all packages concurrently.
breaking MkDocs 2.0 is expected to introduce significant breaking changes, including a rewritten theming system that passes pre-rendered HTML navigation and potentially removing plugin support entirely. This plugin heavily modifies navigation, making it highly likely to be incompatible with MkDocs 2.0 when it is released.
Fix: Until an official update or alternative is provided, users should limit their MkDocs dependency to `<2` (i.e., MkDocs 1.x) to ensure continued functionality. Keep an eye on the plugin's GitHub repository for MkDocs 2.0 compatibility announcements.
gotcha The plugin's functionality relies on explicit configuration in `mkdocs.yml`'s `nav` section where an `index.md` (or similar) is listed as the first child of a section. It does not automatically infer a section index from file structure alone if a `nav` is explicitly defined.
Fix: Always explicitly define the section's index page (e.g., `section-name/index.md`) as the first item under its parent section in your `nav` configuration for the plugin to take effect.

Install

pip install mkdocs-section-index Install with pip

Quickstart

To use mkdocs-section-index, first install it via pip. Then, enable it in your `mkdocs.yml` file under the `plugins` section. Define your navigation (`nav`) structure such that a markdown file (conventionally `index.md`) is specified as the first child of a section. This `index.md` file will then become the clickable index page for that section in the generated documentation.

# mkdocs.yml

site_name: My Project Docs

nav:
  - Home: index.md
  - Guides:
    - guides/index.md  # This page becomes the clickable 'Guides' section index
    - guides/setup.md
    - guides/usage.md
  - API Reference: api/index.md # Another way to define a section index

plugins:
  - search
  - section-index

# --- Expected file structure ---
# ./
# ├── mkdocs.yml
# └── docs/
#     ├── index.md
#     ├── guides/
#     │   ├── index.md
#     │   ├── setup.md
#     │   └── usage.md
#     └── api/
#         └── index.md

view raw JSON →