---
id: mkdocs-include-dir-to-nav
version: "1.2.0"
license: MIT
license_treatment: permissive
maintenance: abandoned
---

# mkdocs-include-dir-to-nav — A MkDocs plugin include all file in dir to navigation

License: permissive · Maintenance: abandoned · Downloads: 74.2K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: abandoned
- Downloads: 74.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs directory navigation expansion, mkdocs folder to nav plugin, auto-generate mkdocs navigation, mkdocs bulk file inclusion, mkdocs nav from directory structure, mkdocs-plugin, documentation-automation

[View on SkillFed](https://skillfed.io/packages/mkdocs-include-dir-to-nav) · [View on PyPI](https://pypi.org/project/mkdocs-include-dir-to-nav/)