mkdocs-literate-nav

What it is and what it does

mkdocs-literate-nav is a MkDocs plugin that replaces the YAML-based nav configuration with Markdown lists. Instead of maintaining a separate nav structure in mkdocs.yml, you write a SUMMARY.md file (or any other Markdown file you choose) containing nested bullet-point lists of links, and the plugin parses it to build your site's navigation tree.

The plugin supports several advanced features: wildcards to match files by pattern, cross-linked subdirectories where each folder can have its own SUMMARY.md, and inferred page ordering that falls back to MkDocs' default behavior when pages aren't explicitly listed. It works well alongside section-index and gen-files plugins, and is designed as a more explicit alternative to awesome-pages. The approach is intentionally opposite to awesome-pages—only directories explicitly mentioned in parent nav files trigger implicit resolution of subdirectories.

Use it for

• Organize documentation where navigation structure mirrors the file layout, using Markdown lists instead of maintaining separate YAML config.
• Build large doc sites with mixed explicit ordering (for important pages) and wildcard patterns (for auto-discovered content).
• Create GitHub-friendly documentation where the nav file (e.g., README.md) displays nicely in the repository while also serving as MkDocs navigation.
• Manage multi-section documentation where each subdirectory maintains its own navigation file independently.
• Migrate from awesome-pages to a more explicit, Markdown-first navigation model.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

mkdocs-literate-nav on PyPI

Before you install

Low install friction with a pure-Python wheel. Active maintenance with recent commits and a stable release history since 2020. Supports current Python versions (3.9–3.13) and depends only on mkdocs and properdocs.

The nav file must be placed at the root of the docs directory; MkDocs must be installed and configured first.

License in practice

MIT license permits commercial and private use with minimal restrictions, making it safe to adopt in any project.

Quickstart

pip install mkdocs-literate-nav

# In mkdocs.yml:
plugins:
  - literate-nav:
      nav_file: SUMMARY.md

# In docs/SUMMARY.md:
* [Home](index.md)
* [Guide](guide.md)
  * [Setup](guide/setup.md)
  * [Usage](guide/usage.md)

Package facts

Evidence: mkdocs_literate_nav-0.6.3-py3-none-any.whl

Tags

More Documentation packages

See also mkdocs-awesome-pages-plugin · mkdocs-include-dir-to-nav · mkdocs-section-index · mkdocs-awesome-nav · mkdocs-redirects · mkdocs-api-autonav · mkdocs-llmstxt · mkdocs-monorepo-plugin · mkdocs-autorefs · zensical

Further reading