{"id":2996,"library":"mkdocs-section-index","title":"MkDocs Section Index Plugin","description":"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.","status":"active","version":"0.3.11","language":"en","source_language":"en","source_url":"https://github.com/oprypin/mkdocs-section-index","tags":["mkdocs","plugin","documentation","navigation","material-for-mkdocs","static-site-generator"],"install":[{"cmd":"pip install mkdocs-section-index","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This is an MkDocs plugin and requires MkDocs to function.","package":"mkdocs"},{"reason":"While not strictly required, the plugin has frequent compatibility updates for MkDocs Material, indicating a common pairing.","package":"mkdocs-material","optional":true}],"imports":[],"quickstart":{"code":"# mkdocs.yml\n\nsite_name: My Project Docs\n\nnav:\n  - Home: index.md\n  - Guides:\n    - guides/index.md  # This page becomes the clickable 'Guides' section index\n    - guides/setup.md\n    - guides/usage.md\n  - API Reference: api/index.md # Another way to define a section index\n\nplugins:\n  - search\n  - section-index\n\n# --- Expected file structure ---\n# ./\n# ├── mkdocs.yml\n# └── docs/\n#     ├── index.md\n#     ├── guides/\n#     │   ├── index.md\n#     │   ├── setup.md\n#     │   └── usage.md\n#     └── api/\n#         └── index.md","lang":"yaml","description":"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."},"warnings":[{"fix":"Monitor announcements from both the mkdocs-section-index and ProperDocs projects for guidance on future compatibility and maintenance strategy.","message":"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.","severity":"breaking","affected_versions":"0.3.11+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"Future MkDocs 2.0 release"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}