Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
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
mkdocs --version
Debug
Known issues
breakingThe 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.fixMonitor announcements from both the mkdocs-section-index and ProperDocs projects for guidance on future compatibility and maintenance strategy.
affects: 0.3.11+
gotchaThe 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.fixRefer 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.
affects: All versions
breakingMkDocs 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.fixUntil 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.
affects: Future MkDocs 2.0 release
gotchaThe 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.fixAlways 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.
affects: All versions
Errors
Common errors & fixes
section-index plugin couldn't detect a supported theme to adapt. It probably won't work as expected.
The mkdocs-section-index plugin requires specific theme overrides or direct support from the theme to function correctly, and this warning appears when an unsupported theme is in use.
fixSwitch to a supported theme like 'material', 'readthedocs', or 'nature' in your `mkdocs.yml` file, or implement custom theme overrides if using an unsupported theme.
TypeError: unsupported operand type(s) for +: 'NoneType' and 'str'
This error typically occurs when the `site_url` configuration option is not defined or is explicitly set to `null` in `mkdocs.yml`, and a plugin (including `mkdocs-section-index` or other MkDocs plugins) attempts to use it in an operation that expects a string.
fixAdd or ensure the `site_url` is correctly defined with a string value in your `mkdocs.yml` file, for example: `site_url: https://example.com/`.
It seems that the effects of section-index plugin have been lost, because another MkDocs plugin re-wrote the nav! Re-order `plugins` in mkdocs.yml so that 'section-index' appears closer to the end.
Another MkDocs plugin listed after `mkdocs-section-index` in `mkdocs.yml` is modifying the navigation object, overwriting the changes made by `mkdocs-section-index`.
fixAdjust the order of plugins in your `mkdocs.yml` file, placing `section-index` after any other plugins that might modify the navigation structure.
Section index pages seems not work
This general issue often arises from an incorrect `nav` configuration in `mkdocs.yml`, where the index page for a section is not structured according to the plugin's expectations or there's a conflict with the MkDocs Material theme version. The plugin requires the index page to be the first item under a section and typically without an explicit title in the `nav` entry for the index page itself.
fixEnsure your `mkdocs.yml` `nav` structure correctly defines section index pages. For example: `nav: - Section Name: - section/index.md - Another Page: section/page.md`. Verify compatibility with your MkDocs Material theme version.
Upgrade
Version history
0.3.11latest on PyPI · released Mar 16, 2026
Audit
Dependencies
mkdocsrequiredThis is an MkDocs plugin and requires MkDocs to function.
mkdocs-materialoptionalWhile not strictly required, the plugin has frequent compatibility updates for MkDocs Material, indicating a common pairing.