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

MkDocs plugin that lets you define site navigation as Markdown lists instead of YAML, with support for wildcards, cross-linked subdirectories, and inferred page ordering.

Yes. The plugin is actively maintained, has no known vulnerabilities, installs with low friction, and uses a permissive MIT license. It solves a genuine pain point—writing navigation as Markdown instead of YAML—and integrates well with the MkDocs ecosystem. Install it if your documentation benefits from Markdown-based nav or if you want finer control over page ordering without maintaining parallel YAML config.

Install

mkdocs-literate-nav on PyPI

pip install mkdocs-literate-nav

uv add mkdocs-literate-nav

poetry add mkdocs-literate-nav

Installing mkdocs-literate-nav

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.

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)

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

Verify before relying

• Whether properdocs is a required runtime dependency or an optional enhancement.
• Performance characteristics when handling very large navigation trees with many wildcards.
• Compatibility with all MkDocs themes and extensions beyond the mentioned section-index and gen-files.

Package facts

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

Keywords: mkdocs, mkdocs-plugin

Tags

More Documentation packages

Further reading