Sorting

Use these options to customize the sorting of pages and sections. They affect all items that aren't explicitly ordered using nav.

Child directories inherit these settings

Sorting options apply to all child directories as well, unless they're overridden by a .nav.yml there.

Sort Direction

Use this option to change the direction from ascending to descending.

descasc (default)

.nav.yml

sort:
  direction: desc

File Structure

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

• Support
• Getting started
• Guides
  • Error handling
  • Authentication

.nav.yml

sort:
  direction: asc

File Structure

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

• Getting started
• Support
• Guides
  • Authentication
  • Error handling

Sort Sections

By default, sections are always sorted after all pages. Use this option to have them before or mixed in with pages.

firstmixedlast (default)

.nav.yml

sort:
  sections: first

File Structure

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

• Guides
  • Authentication
  • Error handling
• Getting started
• Support

.nav.yml

sort:
  sections: mixed

File Structure

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

• Getting started
• Guides
  • Authentication
  • Error handling
• Support

.nav.yml

sort:
  sections: last

File Structure

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

• Getting started
• Support
• Guides
  • Authentication
  • Error handling

Sort Type

awesome-nav uses natural sorting by default. Set this option for strictly alphabetical sorting.

alphabeticalnatural (default)

.nav.yml

sort:
  type: alphabetical

File Structure

docs/
├─ version-9.0.md
├─ version-9.1.md
└─ version-10.0.md

• Version 10.0
• Version 9.0
• Version 9.1

.nav.yml

sort:
  type: natural

File Structure

docs/
├─ version-9.0.md
├─ version-9.1.md
└─ version-10.0.md

• Version 9.0
• Version 9.1
• Version 10.0

Sort Ignore Case

Enable case-insensitive sorting.

Natural sorting

Note that natural sorting (which is the default) already makes sure that lowercase and uppercase are grouped together.
Therefore the option makes most sense when combined with alphabetical sorting.

truefalse (default)

.nav.yml

sort:
  ignore_case: true
  type: alphabetical

File Structure

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

• Getting started
• LICENSE
• Support

.nav.yml

sort:
  ignore_case: false
  type: alphabetical

File Structure

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

• LICENSE
• Getting started
• Support

Sort By

Configure which attribute is used for sorting.

Path & Filename

The difference between path and filename is only relevant with deep glob patterns, otherwise their behavior is identical.

filenamepath (default)

.nav.yml

sort:
  by: filename
nav:
  - "**/*.md"

File Structure

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

• Authentication
• Error handling
• Getting started
• Support

.nav.yml

sort:
  by: path
nav:
  - "**/*.md"

File Structure

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

• Getting started
• Authentication
• Error handling
• Support

Title

Sort sections and pages based on their title instead of path or filename.

.nav.yml

sort:
  by: title

Limitation

Since MkDocs extracts the markdown title when it renders the page, it is not available when awesome-nav is sorting the pages.
In order to have pages properly sorted by their title, add the title to the meta-data at the beginning of the markdown file:

---
title: Getting started
---

Without a title in the meta-data, sorting falls back to the filename.