MkDocs Awesome Nav Plugin

3.3.0 · active · verified Thu Apr 16

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.

Common errors

```
Plugin 'awesome-nav' not found.
```
cause 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.
```
cause 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:...
```
cause 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.

Warnings

breaking The `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.
breaking Version 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`.
gotcha The 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.

Install

pip install mkdocs-awesome-nav Install mkdocs-awesome-nav

Quickstart

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

view raw JSON →