mkdocs-awesome-nav

The mkdocs-awesome-nav plugin (formerly mkdocs-awesome-pages-plugin) provides advanced control over the MkDocs navigation structure. It allows you to manipulate the navigation tree without manually defining the entire structure in mkdocs.yml.

Key capabilities include:

• Adjusting Item Order: Manually re-order items or use sorting options.
• Adding Sections & Links: Create new navigation sections and include external links.
• Customizing Titles: Override section titles or specific page titles.
• Hiding Pages: Hide specific pages or entire sections from the navigation menu (they remain accessible via URL).
• Using Glob Patterns: Use glob patterns to match and show/hide files.

The awesome-nav plugin provides granular control over your MkDocs navigation without requiring you to manually define the entire structure in mkdocs.yml. Instead of the standard MkDocs approach, awesome-nav generates navigation based on your file structure and allows you to apply specific customizations using .nav.yml files placed within your docs directory.

To use this feature, create a .nav.yml file in any directory within your docs folder. This file allows you to augment or override the automatically generated structure for that specific directory and its children.

To hide a directory and all its children from the navigation menu, place a .nav.yml file inside that directory and set the hide option to true.

hide: true

To upgrade from version 2 to version 3, follow these steps:

1. Uninstall the old plugin: pip uninstall mkdocs-awesome-pages-plugin
2. Install the new plugin: pip install mkdocs-awesome-nav
3. Update mkdocs.yml: Replace awesome-pages with awesome-nav in the plugins list.
4. Update configuration files: Rename .pages files to .nav.yml (recommended) and update the syntax according to the changes in mkdocs.yml and .nav.yml configuration keys.

# Example mkdocs.yml update
plugins:
  - awesome-nav

You can insert specific markdown files into your navigation by referencing their path. You can also override the display title using the Title: path/to/file.md syntax.

Note that files can be located in subdirectories relative to the .nav.yml file.

nav:
  - support.md          # Standard reference
  - help/support.md     # Reference in a subdirectory
  - Help: support.md   # Reference with an overridden title

To insert an entire directory as a section in your navigation, reference the directory name. If the directory contains its own .nav.yml file, that file will be used to generate the section, but a title defined in the parent .nav.yml will take precedence.

You can also override the section title using the Title: directory_name syntax.

nav:
  - guides             # Standard directory reference
  - resources/guides   # Sub-directory reference
  - User Guides: guides # Reference with an overridden title

You can customize the sorting of pages and sections using a .nav.yml file. These settings affect all items that are not explicitly ordered using the nav key in your configuration.

Inheritance: Sorting options apply to all child directories unless they are overridden by a local .nav.yml file within that directory.

sort:
  direction: asc
  sections: last
  type: natural
  by: path

You can hide specific directories and pages from the navigation using .gitignore-style glob patterns via the ignore key in a .nav.yml file.

Important: If your pattern starts with *, you must wrap it in quotes to prevent YAML parsing errors (as * is reserved for aliases in YAML).

Patterns are inherited by child directories unless overridden by a local .nav.yml file.

ignore: "*.hidden.md"

You can add links to external websites or relative paths within your navigation structure.

nav:
  - Full Url: https://lukasgeiter.github.io/mkdocs-awesome-nav
  - Relative Path: ../