{"id":8320,"library":"mkdocs-awesome-nav","title":"MkDocs Awesome Nav Plugin","description":"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.","status":"active","version":"3.3.0","language":"en","source_language":"en","source_url":"https://github.com/lukasgeiter/mkdocs-awesome-nav","tags":["mkdocs","documentation","navigation","plugin","static-site-generator"],"install":[{"cmd":"pip install mkdocs-awesome-nav","lang":"bash","label":"Install mkdocs-awesome-nav"}],"dependencies":[{"reason":"Required for any MkDocs plugin. Version 1.5.0 or higher is needed for mkdocs-awesome-nav v3.x.","package":"mkdocs","optional":false},{"reason":"Requires Python 3.10 or higher.","package":"python","optional":false}],"imports":[],"quickstart":{"code":"# mkdocs.yml\nsite_name: My Awesome Docs\n\nplugins:\n  - awesome-nav\n\nnav:\n  - Home: index.md\n  - 'User Guide':\n      - guide/*.md # Example of a glob pattern\n  - 'API Reference': api/\n\n# To build the site:\n# mkdocs build\n# To serve the site locally:\n# mkdocs serve\n","lang":"yaml","description":"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."},"warnings":[{"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.","message":"The `nav_sections` configuration option was removed in version 3.0.0 and replaced by the `sections` option, which has different functionality.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"Version 3.0.0 and higher of mkdocs-awesome-nav requires MkDocs >= 1.5.0 and Python >= 3.10.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Add `awesome-nav` to your `plugins` list: \n```yaml\nplugins:\n  - awesome-nav\n```\nEnsure there are no indentation errors.","message":"The plugin must be explicitly listed under the `plugins:` section in your `mkdocs.yml` file to be active.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the plugin is installed (`pip install mkdocs-awesome-nav`) and correctly listed as `awesome-nav` under `plugins` in your `mkdocs.yml`.","cause":"The plugin `mkdocs-awesome-nav` is either not installed or is misspelled in the `mkdocs.yml` file.","error":"Plugin 'awesome-nav' not found."},{"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.","cause":"You are using the deprecated `nav_sections` option with mkdocs-awesome-nav v3.x or higher.","error":"Configuration error: The option 'nav_sections' is not allowed for the awesome-nav plugin."},{"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.","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.","error":"mkdocs.plugins.base.PluginCollectionError: Plugin 'awesome-nav' could not be loaded: ImportError: 'mkdocs' requires a 'plugins' object with the following attributes:..."}]}