---
id: mkdocs-awesome-nav
version: "3.3.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# mkdocs-awesome-nav — A plugin for customizing the navigation structure of your MkDocs site.

License: permissive · Maintenance: active · Downloads: 1.1M/mo

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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs navigation customization, mkdocs nav plugin, mkdocs page ordering, mkdocs navigation structure, mkdocs external links nav, mkdocs hide pages, mkdocs glob patterns navigation, mkdocs-plugin, documentation-tooling

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