Custom Navigation

The nav option gives you full control over the navigation structure. The basic syntax is the same as in mkdocs.yml, but it can be defined in any directory and has more powerful features like glob patterns.

This example shows off the different kinds of nav entries:

.nav.yml

nav:
  - getting-started.md #(1)!
  - guides #(2)!
  - More Resources: #(3)!
    - "*" #(4)!
    - MkDocs: https://mkdocs.org #(5)!

Insert individual pages
Read more below
Insert entire directories as sections
Read more below
Create sections
Read more below
Insert all files and directories that match glob patterns
Read more below
Create external links
Read more below

File Structure

docs/
├─ .nav.yml
├─ getting-started.md
├─ support.md
└─ guides/
   ├─ authentication.md
   └─ error-handling.md

Getting started
Guides
- Authentication
- Error handling
More Resources
- Support
- MkDocs

Pages

Reference a markdown file to insert that page into that spot in the navigation:

.nav.yml

nav:
  - support.md

File Structure

docs/
├─ .nav.yml
└─ support.md

Support

The markdown file can be located in a different directory:

.nav.yml

nav:
  - help/support.md

File Structure

docs/
├─ .nav.yml
└─ help/
   └─ support.md

Support

You can also override the title that is displayed in the navigation:

.nav.yml

nav:
  - Help: support.md

File Structure

docs/
├─ .nav.yml
└─ support.md

Help

Directories

Reference a directory to insert it as section into that spot in the navigation:

.nav.yml

nav:
  - guides

File Structure

docs/
├─ .nav.yml
└─ guides/
   ├─ authentication.md
   └─ error-handling.md

Guides
- Authentication
- Error handling

This can be a sub-directory as well:

.nav.yml

nav:
  - resources/guides

File Structure

docs/
├─ .nav.yml
└─ resources/
   └─ guides/
      ├─ authentication.md
      └─ error-handling.md

Guides
- Authentication
- Error handling

You can also override the title that is displayed in the navigation:

.nav.yml

nav:
  - User Guides: guides

File Structure

docs/
├─ .nav.yml
└─ guides/
   ├─ authentication.md
   └─ error-handling.md

User Guides
- Authentication
- Error handling

Tip

If the referenced directory contains a .nav.yml file, it will of course be taken into account when generating the section.
A title defined here takes precedence over the title in the .nav.yml from inside the directory.

Glob Patterns

Specify a glob pattern to insert all files and directories that match it.

Let's begin a with a simple example, * matches everything in the current directory:

.nav.yml

nav:
  - "*"

File Structure

docs/
├─ .nav.yml
├─ getting-started.md
├─ support.md
└─ guides/
   ├─ authentication.md
   └─ error-handling.md

Getting started
Support
Guides
- Authentication
- Error handling

Patterns that start with * need to be wrapped in quotes

YAML uses * at the beginning of nodes for aliases. Make sure to wrap your pattern in quotes if it starts with *.

Without the quotes, you get the following error:

ERROR   -  awesome-nav: Parsing error [.nav.yml]
           while scanning an alias
             in "<unicode string>", line 4, column 5:
                 - *
                   ^
           expected alphabetic or numeric character, but found '\x00'
             in "<unicode string>", line 4, column 6:
                 - *
                    ^

On its own, the * pattern isn't very useful. Omitting nav entirely would've had the same result. It becomes really useful when combined with other entries however. You can explicitly specify the entries that you want to control and have the rest of the navigation filled in automatically:

.nav.yml

nav:
  - getting-started.md
  - "*"
  - MkDocs: https://mkdocs.org

File Structure

docs/
├─ .nav.yml
├─ getting-started.md
├─ support.md
└─ guides/
   ├─ authentication.md
   └─ error-handling.md

Getting started
Support
Guides
- Authentication
- Error handling
MkDocs

No repeated matches

Notice how getting-started.md does not appear twice in the navigation. Glob patterns will never match files or directories that are already part of the navigation. If you're looking to create a navigation item for a page without excluding it from a glob pattern, create a link instead of the page entry.

Examples

Glob patterns allow you to do a lot more than just * of course. Here are some examples of what's possible:

Only markdown filesOnly directoriesFiles with a suffixLogical OR

.nav.yml

nav:
  - "*.md"

File Structure

docs/
├─ .nav.yml
├─ getting-started.md
├─ support.md
└─ guides/
   ├─ authentication.md
   └─ error-handling.md

Getting started
Support

.nav.yml

nav:
  - "*/"

File Structure

docs/
├─ .nav.yml
├─ getting-started.md
├─ support.md
└─ guides/
   ├─ authentication.md
   └─ error-handling.md

Guides
- Authentication
- Error handling

.nav.yml

nav:
  - "*.public.md"

File Structure

docs/
├─ .nav.yml
├─ getting-started.public.md
└─ support.md

Getting started

.nav.yml

nav:
  - "*.@(public|published).md"

File Structure

docs/
├─ .nav.yml
├─ getting-started.public.md
├─ release-notes.published.md
└─ support.md

Getting started
Release notes

Pattern syntax

This feature uses wcmatch under the hood. Check out their documentation for more details on the pattern syntax. Enabled flags: GLOBSTAR | EXTGLOB

Deep Matches

Patterns can also target files in nested directories:

All pagesOne level deep

.nav.yml

nav:
  - "**/*.md"

File Structure

docs/
├─ .nav.yml
├─ getting-started.md
├─ support.md
└─ guides/
   ├─ authentication.md
   └─ error-handling.md

Getting started
Authentication
Error handling
Support

.nav.yml

nav:
  - "*/index.md"

File Structure

docs/
├─ .nav.yml
├─ guides
│  ├─ authentication.md
│  ├─ index.md
│  └─ error-handling.md
└─ help
   ├─ index.md
   └─ support.md

Guides
Help

Flattening

Matching files and directories are inserted into the navigation as a flat list. By default, they are still sorted by path though. This can be changed using the sort.by option.

Options

To set additional options for a glob pattern, use the following syntax:

nav:
  - glob: "*"
    sort:
      direction: desc

These are all the available options:

TableExample

Option	Description
`ignore_no_matches`	Set to `true` to disable the message that is printed when this glob pattern doesn't match any files or directories.
`preserve_directory_names`	Disable formatting of generated directory titles. Read more
`flatten_single_child_sections`	For sections with a single child, show the child instead of the section. Read more
`ignore`	Everything that matches this glob pattern is hidden. Read more
`sort`	All the regular sorting options. Read more

nav:
  - glob: "*"
    ignore_no_matches: true
    preserve_directory_names: true
    flatten_single_child_sections: true
    ignore: "*.hidden.md"
    sort:
      direction: asc
      type: natural
      by: filename
      sections: last

Sections

You can create a section that is not derived from a file directory like this:

.nav.yml

nav:
  - More Resources:
    - support.md

File Structure

docs/
├─ .nav.yml
└─ support.md

More Resources
- Support

Tip

Inside the section you can use all the same entries as at the top level - including nested sections.

Links

You may add external links to the navigation:

.nav.yml

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