mkdocs-awesome-nav

What it is and what it does

Awesome Nav is a MkDocs plugin that gives you declarative control over your documentation site's navigation without hand-writing the entire structure. Instead of manually listing every page in your mkdocs.yml, you define rules in a separate nav configuration file—reorder items, create sections, add external links, hide pages, and use glob patterns to match files. It sits on top of MkDocs and relies on natsort for sorting, pydantic for configuration validation, and wcmatch for glob pattern matching.

The plugin is useful when your documentation grows beyond a handful of pages and you want flexible, maintainable control over how visitors navigate it. It's actively maintained, has no known security vulnerabilities, and is in the top 5000 PyPI packages by download volume.

Use it for:

• Reorder documentation pages without editing mkdocs.yml directly, using sorting rules or manual ordering.
• Hide sensitive or draft pages from navigation while keeping them accessible by direct URL.
• Add external links (e.g., to a blog or external resource) directly in the navigation tree.
• Match and organize pages using glob patterns instead of listing them one by one.
• Customize page titles in navigation independently of their actual file names or frontmatter.

Worth the install?

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

A MkDocs plugin that lets you customize your site's navigation structure through configuration files instead of manually editing the entire nav tree.

Yes. The plugin is actively maintained, has low install friction, carries a permissive MIT license, and solves a real problem for MkDocs users managing growing documentation. No known vulnerabilities. Install it if you're using MkDocs and want more flexible navigation control than the default config allows.

Install

mkdocs-awesome-nav on PyPI

pip install mkdocs-awesome-nav

uv add mkdocs-awesome-nav

poetry add mkdocs-awesome-nav

Installing mkdocs-awesome-nav

Before you install

Low friction install with a stable, recently-active codebase. The package depends on mkdocs, natsort, pydantic, and wcmatch—all common, well-maintained libraries. Last commit was 2026-04-10 and the project is marked active.

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute this plugin freely in both open and closed projects with minimal restrictions.

Quickstart

pip install mkdocs-awesome-nav

Then add to mkdocs.yml:
plugins:
  - awesome-nav

Requires Python 3.10 or later.

Verify before relying

• Whether the plugin works with all current MkDocs versions or has specific version constraints beyond what the fact sheet states.

Package facts

Evidence: mkdocs_awesome_nav-3.3.0-py3-none-any.whl

Keywords: mkdocs, markdown, documentation, navigation

Tags

More Documentation packages

Further reading