Registry / web-framework / mkdocs-awesome-nav

mkdocs-awesome-nav

library3.3.0pypypiunverified

A plugin for customizing the navigation structure of your MkDocs site. It enhances the standard MkDocs navigation with features like glob patterns, dynamic sorting, and conditional visibility, allowing for more flexible site organization. The current version is 3.3.0, and it follows a feature-driven release cadence with occasional major updates.

web-framework devops

pip install mkdocs-awesome-nav

github ↗package ↗

INSTALL

IMPORT

SIG · MKDOCS-AWESOME-NAV

mkdocs-awesome-nav

web-frameworkpythonv3.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

To use the mkdocs-awesome-nav plugin, you must first install it and then enable it in your `mkdocs.yml` configuration file under the `plugins` section. This example demonstrates a basic navigation setup including a glob pattern for automatic file inclusion.

# mkdocs.yml site_name: My Awesome Docs plugins: - awesome-nav nav: - Home: index.md - 'User Guide': - guide/*.md # Example of a glob pattern - 'API Reference': api/ # To build the site: # mkdocs build # To serve the site locally: # mkdocs serve

Debug

Known issues

breakingThe `nav_sections` configuration option was removed in version 3.0.0 and replaced by the `sections` option, which has different functionality.

fix

If upgrading from v2.x, review your `nav_sections` usage. For similar functionality, consider using `sections` for managing hidden content or the main `nav` for primary structure. Refer to the v3.x documentation.

affects: >=3.0.0

breakingVersion 3.0.0 and higher of mkdocs-awesome-nav requires MkDocs >= 1.5.0 and Python >= 3.10.

fix

Ensure your MkDocs installation is at least version 1.5.0 (`pip install "mkdocs>=1.5.0"`) and your Python environment is 3.10 or newer. Check your `mkdocs --version` and `python --version`.

affects: >=3.0.0

gotchaThe plugin must be explicitly listed under the `plugins:` section in your `mkdocs.yml` file to be active.

fix

Add `awesome-nav` to your `plugins` list: 
```yaml
plugins:
  - awesome-nav
```
Ensure there are no indentation errors.

affects: All versions

Errors

Common errors & fixes

Plugin 'awesome-nav' not found.

The plugin `mkdocs-awesome-nav` is either not installed or is misspelled in the `mkdocs.yml` file.

fix

Ensure the plugin is installed (`pip install mkdocs-awesome-nav`) and correctly listed as `awesome-nav` under `plugins` in your `mkdocs.yml`.

Configuration error: The option 'nav_sections' is not allowed for the awesome-nav plugin.

You are using the deprecated `nav_sections` option with mkdocs-awesome-nav v3.x or higher.

fix

Remove `nav_sections` from your `mkdocs.yml`. If you need to manage navigation sections, consult the v3.x documentation for alternatives, primarily using the main `nav` section or the new `sections` configuration.

mkdocs.plugins.base.PluginCollectionError: Plugin 'awesome-nav' could not be loaded: ImportError: 'mkdocs' requires a 'plugins' object with the following attributes:...

This error can occur if your MkDocs version is too old for `mkdocs-awesome-nav` v3.x, or there's a fundamental issue with the MkDocs installation.

fix

Upgrade MkDocs to version 1.5.0 or higher: `pip install --upgrade "mkdocs>=1.5.0"`. Also, verify your Python version is 3.10 or newer.

Upgrade

Version history

3.3.0latest on PyPI · released Dec 2, 2025

Audit

Dependencies

mkdocsrequiredRequired for any MkDocs plugin. Version 1.5.0 or higher is needed for mkdocs-awesome-nav v3.x.

pythonrequiredRequires Python 3.10 or higher.

Agent activity

3 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lukasgeiter/mkdocs-awesome-nav ↗

packagehttps://pypi.org/project/mkdocs-awesome-nav/ ↗