Navigation Enhancement¶

In a default installation of MkDocs-Material site navigation is configured in mkdocs.yml.

The Awesome Nav for MkDocs plugin (formerly called mkdocs-awesome-pages-plugin) provides full control over the site’s navigation structure. This plugin provides flexibility by using a directory-specific configuration file (.pages).

Feature highlights¶

Adjusting Item Order: Manually re-order navigation items or use the extensive sorting options.
Adding Sections & Links: Create sections and add external links.
Customizing Titles: Change the title of sections and override page titles.
Hiding Pages: Hide pages or entire sections from the navigation, making them only accessible by url.
Using Glob Patterns: Match files using glob patterns to show or hide them.

Collapse single nested pages¶

If you have directories that only contain a single page, awesome-pages can “collapse” them, so the folder doesn’t show up in the navigation (by default this feature is turned off).

collapse_single_pages: false

You can set this feature in a directory (.pages) or globally in mkdocsd.yml.

You can apply per-directory overrides by placing a special file named .pages inside any folder where you want to change the behavior. This file tells MkDocs to ignore the global rules for that specific folder. The .pages file is a special configuration file used by the mkdocs-awesome-nav plugin to customize navigation for a specific folder.

Note

The mkdocs-awesome-nav plugin is not bundled inside the core Material for MkDocs package.

Hide directory¶

Create a YAML file named .pages in a directory and set the hide attribute to true to hide the directory, including all sub-pages and sub-sections, from the navigation:

hide: true

Note

This option only hides the section from the navigation. It will still be included in the build and can be accessed under its URL.

Set directory title¶

Create a YAML file named .pages in a directory and set the title to override the title of that directory in the navigation:

title: Page Title

Arrange pages¶

Create a YAML file named .pages in a directory and set the arrange attribute to change the order of how child pages appear in the navigation. This works for .md pages as well as subdirectories.

title: Page Title
arrange:
    - page1.md
    - page2.md
    - subdirectory

If you only specify some pages, they will be positioned at the beginning, followed by the other pages in their original order.

You may also include a ‘…’ entry at some position to specify where the rest of the pages should be inserted:

arrange:
    - index.md
    - ...
    - styling.md

In this example ‘index.md’ is positioned at the beginning, styling.md at the end, and the rest of the pages are alphabetically listed in between.