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 on it.

Install

mkdocs-include-dir-to-nav on PyPI

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.

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

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

Package facts

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

Tags

More Documentation packages

See also mkdocs-awesome-nav · mkdocs-awesome-pages-plugin · mkdocs-literate-nav · mkdocs-monorepo-plugin · mkdocs-include-markdown-plugin · mkdocs-api-autonav · mkdocs-multirepo-plugin · mkdocs-section-index · mkdocs-autorefs · mdx-include

Further reading