mkdocs-include-dir-to-nav

What it is and what it does

This is a MkDocs plugin that solves a specific problem: MkDocs does not automatically expand folder references in navigation configuration into their contained files. This plugin scans your navigation entries during build or serve and replaces directory paths with all matching markdown files found within them, optionally organizing them into nested sections.

You configure it by listing folder paths in your mkdocs.yml nav section, and the plugin expands them on the fly without modifying your configuration file. It offers granular control through options like recursive scanning, file pattern matching, sorting, and whether to flatten subdirectories or preserve them as sections. The plugin supports all standard mkdocs file reference formats.

Use it for:

• Automatically populate a large documentation site's navigation from a folder structure without manually listing every file.
• Keep navigation configuration simple while maintaining a flexible docs directory layout that grows over time.
• Organize documentation into nested sections by folder while letting the plugin handle the nav entry generation.
• Filter which markdown files appear in navigation using regex patterns on filenames.
• Sort documentation pages alphabetically or in custom order without hand-editing the nav config.

Worth the install?

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

A MkDocs plugin that automatically expands directory references in navigation configuration into individual markdown file entries, with options to control sorting, recursion, and hierarchy.

No. The project is abandoned with no commits since 2022-03-01. While it has low install friction and permissive licensing, the lack of maintenance means it will not receive bug fixes or compatibility updates as mkdocs evolves. For active documentation sites, consider maintained alternatives.

Install

mkdocs-include-dir-to-nav on PyPI

pip install mkdocs-include-dir-to-nav

uv add mkdocs-include-dir-to-nav

poetry add mkdocs-include-dir-to-nav

Installing mkdocs-include-dir-to-nav

Before you install

Low install friction with a single runtime dependency on mkdocs. However, the project is abandoned—last commit was 2022-03-01. No active maintenance means bug fixes or compatibility updates are unlikely.

License in practice

MIT license is permissive; you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart

pip install mkdocs-include-dir-to-nav

Then in mkdocs.yml:
plugins:
  - search
  - include_dir_to_nav

Requires mkdocs to be installed and a mkdocs.yml configuration file with a docs directory containing markdown files.

Verify before relying

• Compatibility with mkdocs versions released after 2022-03-01 is unknown.
• Whether the plugin works correctly with current Python versions is not documented.
• Active maintenance status and likelihood of future updates.

Package facts

Evidence: mkdocs_include_dir_to_nav-1.2.0-py3-none-any.whl

Keywords: mkdocs, navigation, plugin, directory, folder

Tags

More Documentation packages

Further reading