mkdocs-section-index

What it is and what it does

This MkDocs plugin solves a core limitation of MkDocs navigation: normally, section headers are not clickable and cannot link to a page. The plugin enables a hybrid nav item that acts as both a section container and a clickable page by merging an index.md file into the section itself. When you structure your nav with a section containing an index.md as its first child, the plugin combines them into a single nav item that is both clickable (linking to the index page) and able to hold subsections and child pages.

The plugin works by introducing a special "section-page" object into MkDocs' nav structure and then patching the templates of supported themes (material, readthedocs, nature) to render these hybrid items correctly. It requires Python 3.10 or later and depends on mkdocs and properdocs. The codebase is actively maintained and carries no known security vulnerabilities.

Use it for:

• Create documentation where category headers are clickable landing pages with overview content and links to subcategories
• Build hierarchical docs where each section has both an introduction page and nested child pages
• Migrate documentation from systems that support clickable sections without restructuring your entire nav
• Use index.md files as section introductions that are also accessible via the nav hierarchy

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

MkDocs plugin that makes section headers clickable by merging an index page into the section itself, allowing sections to function as both navigation containers and destination pages.

Yes. The plugin solves a genuine UX gap in MkDocs with low install friction, active maintenance, permissive licensing, and no security vulnerabilities. Install it if you use material, readthedocs, or nature themes and want clickable section headers. If you use a different theme, verify that template patching will work or that your theme already supports hybrid section-page items.

Install

mkdocs-section-index on PyPI

pip install mkdocs-section-index

uv add mkdocs-section-index

poetry add mkdocs-section-index

Installing mkdocs-section-index

Before you install

Low friction: pure Python wheel with only mkdocs and properdocs as runtime dependencies. Active maintenance with a recent release (120 days ago) and a stable codebase (96 stars, no archived status).

License in practice

MIT license (permissive) means you can use, modify, and distribute this plugin freely with minimal restrictions, making it safe for both commercial and open-source documentation projects.

Quickstart

pip install mkdocs-section-index

# In mkdocs.yml, add to plugins:
plugins:
  - search
  - section-index

# Then structure nav with index.md as first child of a section:
nav:
  - Borgs:
    - borgs/index.md
    - Bar: borgs/bar.md

Requires Python 3.10 or later. Theme support is limited to material, readthedocs, and nature; other themes require custom template patches.

Verify before relying

• Whether the plugin works with MkDocs versions beyond the current stable release
• Performance impact on large documentation sites with many sections
• Compatibility with other MkDocs plugins beyond search

Package facts

Evidence: mkdocs_section_index-0.3.12-py3-none-any.whl

Keywords: mkdocs, mkdocs-plugin

Tags

More Documentation packages