### Install Awesome Nav with uv

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/index.md

Install the awesome-nav plugin using uv.

```shell
uv add mkdocs-awesome-nav
```

--------------------------------

### Complete Project Structure Example

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Illustrates a typical project structure with multiple subdirectories and configuration files for MkDocs Awesome Nav.

```tree
docs/
├─ .nav.yml
├─ index.md
├─ getting-started.md
├─ guides/
│  ├─ .nav.yml
│  ├─ authentication.md
│  └─ error-handling.md
├─ api/
│  ├─ .nav.yml
│  ├─ users.md
│  └─ apps.md
└─ internal/
   ├─ .nav.yml
   └─ roadmap.md
```

--------------------------------

### Guides Directory .nav.yml

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Configuration for the 'guides' subdirectory, setting a custom title and sorting navigation items in ascending order.

```yaml
# docs/guides/.nav.yml
title: Guides
sort:
  direction: asc
```

--------------------------------

### Full .nav.yml Configuration Reference

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Example of a comprehensive `.nav.yml` file showing all available configuration options for a directory. Settings are inherited by child directories unless overridden.

```yaml
# docs/.nav.yml  — all options shown with their defaults

title: My Section            # Custom section title (no default; uses formatted directory name)
preserve_directory_names: false  # true = keep exact dir name; false = auto-format
hide: false                  # true = hide this directory from navigation
flatten_single_child_sections: false  # true = collapse sections with only one child
use_index_title: false       # true = use index.md frontmatter title as section title
append_unmatched: false      # true = automatically append files not listed in nav

ignore: "*.hidden.md"        # gitignore-style glob; use list for multiple patterns
# ignore:
#   - "*.hidden.md"
#   - hidden/
#   - $inherit            # extend inherited patterns instead of replacing them

sort:
  direction: asc            # asc | desc
  type: natural             # natural (default) | alphabetical
  by: path                  # path (default) | filename | title
  sections: last            # last (default) | first | mixed
  ignore_case: false        # true = case-insensitive sort

nav:
  - index.md
  - getting-started.md
  - guides
  - "API Reference":
    - api/users.md
    - api/apps.md
  - "*"
  - Website: https://example.com
```

--------------------------------

### Match Everything with `*`

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Use `*` to match all files and directories in the current directory. Patterns starting with `*` must be quoted to avoid YAML alias parsing errors.

```yaml
nav:
  - "*"
```

--------------------------------

### Flatten Multiple Children Sections with Glob Patterns

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/flattening.md

To flatten a section with multiple children, use a glob pattern like `guides/*` in your `nav` configuration. This will list all markdown files within the `guides` directory directly in the navigation.

```yaml
nav:
  - guides/*
```

--------------------------------

### Ignore Specific Files with Glob Patterns in .nav.yml

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/hiding.md

Use the `ignore` option with glob patterns to hide files matching the pattern. Patterns starting with `*` must be quoted to avoid YAML alias errors.

```yaml
ignore: "*.hidden.md"
```

--------------------------------

### MkDocs Configuration with Awesome Nav Plugin

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Basic MkDocs configuration file enabling the search plugin and MkDocs Awesome Nav plugin, with specific logging options for nav overrides.

```yaml
# mkdocs.yml
site_name: My Project
plugins:
  - search
  - awesome-nav:
      logs:
        nav_override: info
```

--------------------------------

### Enable Awesome Nav Plugin in mkdocs.yml

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/index.md

Enable the awesome-nav plugin in your mkdocs.yml configuration file. Ensure 'search' is also enabled if desired.

```yaml
plugins:
   - search
   - awesome-nav
```

--------------------------------

### Configure Awesome Nav Plugin Options

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Customize plugin behavior by setting options in `mkdocs.yml`. Options include renaming the configuration file and controlling log verbosity for various messages.

```yaml
plugins:
  - awesome-nav:
      filename: awesome_nav.yml       # default: .nav.yml
      logs:
        nav_override: info            # default: warning (info if monorepo plugin detected)
        root_title: warning           # default: warning
        root_hide: warning            # default: warning
        no_matches: info              # default: warning
# Supported log levels: info | warning | error
```

--------------------------------

### Basic Glob Pattern in Nav

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Use a basic wildcard '*' to match all remaining files and directories after explicitly listed items.

```yaml
# docs/.nav.yml

# --- Basic wildcard ---
nav:
  - "getting-started.md"    # explicit first
  - "*"                     # match all remaining files and directories
  - MkDocs: https://mkdocs.org
```

--------------------------------

### Glob with Per-Pattern Options

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Configure specific options for a glob pattern, including sorting, ignoring files, and flattening behavior.

```yaml
# docs/.nav.yml

# --- Glob with per-pattern options ---
nav:
  - glob: "*"
    sort:
      direction: desc
      type: natural
    ignore: "*.draft.md"
    flatten_single_child_sections: true
    preserve_directory_names: true
    ignore_no_matches: true
    append_unmatched: false
```

--------------------------------

### Root .nav.yml Configuration

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Root-level configuration for navigation, including sorting, flattening single-child sections, and defining the navigation structure with glob patterns and external links.

```yaml
# docs/.nav.yml
sort:
  type: natural
  sections: first
flatten_single_child_sections: true

nav:
  - index.md
  - getting-started.md
  - guides
  - API Reference: api
  - More:
    - "*.md"
    - GitHub: https://github.com/example/project
```

--------------------------------

### Glob Pattern with Options

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Use glob patterns to dynamically include files in navigation. Options like `sort`, `ignore_no_matches`, `preserve_directory_names`, `flatten_single_child_sections`, and `ignore` can customize glob behavior.

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

```yaml
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
```

--------------------------------

### Match Only Directories

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Use the `*/` pattern to include only directories. This will list the directories themselves, not their contents.

```yaml
nav:
  - "*/"
```

--------------------------------

### Glob Pattern for Directories Only

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Use the '*/' pattern to include only directories in the navigation.

```yaml
# docs/.nav.yml

# --- Only directories ---
nav:
  - "*/"
```

--------------------------------

### Combine Explicit Entries with `*`

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Mix explicit navigation entries with a glob pattern like `*`. The glob pattern will include all remaining files and directories not already listed. Explicitly listed items are not duplicated.

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

--------------------------------

### Respect MkDocs not_in_nav

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Awesome Nav respects MkDocs' 'not_in_nav' configuration, ensuring pages excluded there are also excluded from navigation.

```yaml
# docs/.nav.yml — compatible with MkDocs not_in_nav
# mkdocs.yml:
# not_in_nav: |
#   /private/*
# awesome-nav respects not_in_nav and will exclude those pages too
```

--------------------------------

### API Directory .nav.yml

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Configuration for the 'api' subdirectory, setting a custom title and specifying sorting by filename with mixed section ordering.

```yaml
# docs/api/.nav.yml
title: REST API
use_index_title: false
sort:
  by: filename
  sections: mixed
```

--------------------------------

### Configure .nav.yml for Navigation

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/reference.md

Define custom titles, control directory visibility, flatten single-child sections, ignore files, and configure sorting and navigation structure within your .nav.yml file.

```yaml
title: Lorem Ipsum

preserve_directory_names: true

hide: true

flatten_single_child_sections: true

ignore: "*.hidden.md"

sort:
  direction: asc
  type: natural
  by: filename
  sections: last
  ignore_case: true

nav:
  - getting-started.md
  - guides
  - More Resources:
    - "*"
    - Website: https://lukasgeiter.github.io/mkdocs-awesome-nav

append_unmatched: true

use_index_title: true
```

--------------------------------

### Referencing an Individual Page

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Insert a specific markdown file into the navigation. The title displayed can be overridden by providing a key-value pair.

```yaml
nav:
  - support.md
```

```yaml
nav:
  - help/support.md
```

```yaml
nav:
  - Help: support.md
```

--------------------------------

### Flatten Multiple Children with Deep Glob

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Use a deep glob pattern like 'guides/*' directly within the 'nav' list to flatten multiple children into the parent section, bypassing a dedicated section for the directory.

```yaml
# Flatten multiple children using a deep glob in nav
# docs/.nav.yml
nav:
  - guides/*    # inserts all files inside guides/ directly, without a "Guides" section
# Before: Guides → Authentication, Error handling
# After:  Authentication, Error handling
```

--------------------------------

### Custom Navigation Structure with nav Key

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Define a custom navigation order and structure using the `nav` key in `.nav.yml`. Supports pages, directories, sections, glob patterns, and external links.

```yaml
# docs/.nav.yml
nav:
  - index.md                          # insert a specific page
  - Help: support.md                  # insert page with custom title
  - guides                            # insert a directory as a section
  - "User Guides": resources/guides     # insert subdirectory with custom title
  - "More Resources":                   # manually create a new section
    - api/users.md
    - api/apps.md
    - "*"                             # glob: match all remaining items
    - MkDocs: https://mkdocs.org      # external link
  - "Release Notes": ../changelog.md    # page from a different directory
```

--------------------------------

### Append Unmatched Files (Enabled)

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Automatically include files and directories not explicitly referenced in the `nav` configuration at the end of the navigation. This setting can be overridden in child directories.

```yaml
append_unmatched: true
nav:
  - getting-started.md
  - guides
```

--------------------------------

### Glob Pattern for Suffix Matching

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Match files with a specific suffix, like '*.public.md', to include them in the navigation.

```yaml
# docs/.nav.yml

# --- Files with a naming convention suffix ---
nav:
  - "*.public.md"
```

--------------------------------

### Append Unmatched Files (Disabled)

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

By default, unmatched files and directories are not included in the navigation. This behavior can be explicitly set to `false`.

```yaml
append_unmatched: false
nav:
  - getting-started.md
  - guides
```

--------------------------------

### Referencing a Directory

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Include an entire directory as a section in the navigation. The title can be customized by specifying a key. If the directory contains a `.nav.yml` file, its structure will be respected, but the title defined here takes precedence.

```yaml
nav:
  - guides
```

```yaml
nav:
  - resources/guides
```

```yaml
nav:
  - User Guides: guides
```

--------------------------------

### Use Index.md Title: false (default)

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/titles.md

With 'use_index_title: false' or when not specified, the plugin falls back to using the directory name for navigation titles, unless overridden by other settings.

```yaml
use_index_title: false
```

```yaml
---
title: User Guide Documentation
---
# User Guide

Welcome to the user guide!
```

--------------------------------

### Place Sections After Pages (Default)

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

Set `sort.sections: last` to have all sections appear after all pages. This is the default behavior for section placement.

```yaml
sort:
  sections: last
```

--------------------------------

### Sort by Filename

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Sort navigation items by their filename, which is particularly useful with deep globs like '**/*.md'.

```yaml
# docs/.nav.yml

# --- Sort by filename (relevant with deep globs) ---
sort:
  by: filename
nav:
  - "**/*.md"
# Result: sorted by filename only, ignoring parent path
```

--------------------------------

### Default Unmatched Files Behavior

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

By default, `append_unmatched` is `false`, and files not referenced in `nav` are excluded, with MkDocs logging a warning.

```yaml
# append_unmatched: false (default)
nav:
  - getting-started.md
  - guides
# support.md is excluded from navigation; MkDocs logs:
# INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration:
#          - support.md
```

--------------------------------

### Logical OR with EXTGLOB

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Employ the EXTGLOB flag for logical OR operations within glob patterns, such as matching '*.@(public|published).md'.

```yaml
# docs/.nav.yml

# --- Logical OR with EXTGLOB ---
nav:
  - "*.@(public|published).md"
```

--------------------------------

### One Level Deep Glob

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Use '*/index.md' to include only index files from immediate subdirectories.

```yaml
# docs/.nav.yml

# --- One level deep: only index files from immediate subdirs ---
nav:
  - "*/index.md"
```

--------------------------------

### Ignore Multiple Patterns in .nav.yml

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/hiding.md

Provide a list of glob patterns to the `ignore` option to hide multiple files or directories.

```yaml
ignore:
  - "*.hidden.md"
  - hidden/
```

--------------------------------

### Logical OR in Glob Patterns

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Combine multiple file patterns using the `|` operator within parentheses, such as `*.@(public|published).md`, to match files that satisfy any of the specified conditions.

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

--------------------------------

### Sort by Path (Default)

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

The default `sort.by: path` sorts items based on their full path. This is identical to `filename` sorting unless deep glob patterns are used.

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

--------------------------------

### External and Relative Links

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Add external website links or relative paths to your navigation. This is useful for linking to related projects or external documentation.

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

--------------------------------

### Sort by Page Title

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Sort navigation items by the 'title' specified in the frontmatter of each markdown file. Requires frontmatter 'title' in each .md file.

```yaml
# docs/.nav.yml

# --- Sort by page title (requires frontmatter title in each .md file) ---
sort:
  by: title
# Each .md should have: ---
title: My Page Title
---
```

--------------------------------

### Place Sections Before Pages

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

Set `sort.sections: first` to ensure that all sections appear before any pages in the navigation. This is useful for grouping related content.

```yaml
sort:
  sections: first
```

--------------------------------

### Internal Directory .nav.yml

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Configuration for the 'internal' subdirectory, using the `hide: true` option to prevent its contents from appearing in the navigation.

```yaml
# docs/internal/.nav.yml
hide: true
# roadmap.md is still accessible at /internal/roadmap/ but not shown in nav
```

--------------------------------

### Customize Log Level for Nav Override

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/options.md

Set the log level for 'nav' config overrides to 'info'. Supported levels are 'info', 'warning', and 'error'.

```yaml
plugins:
  - awesome-nav:
      logs:
        nav_override: info
```

--------------------------------

### Match `index.md` in One Level Deep Directories

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Use the `*/index.md` pattern to match `index.md` files located directly within subdirectories. This flattens the navigation, listing only the matched `index.md` files.

```yaml
nav:
  - "*/index.md"
```

--------------------------------

### Custom Navigation Section

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Create a navigation section that is not directly tied to a file directory. This allows for custom structuring of your site's navigation.

```yaml
nav:
  - More Resources:
    - support.md
```

--------------------------------

### Sort by Filename

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

Use `sort.by: filename` to sort items based on their filename. This is identical to `path` sorting unless deep glob patterns are used.

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

--------------------------------

### Match Only Markdown Files

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Use the `*.md` pattern to include only files ending with the `.md` extension.

```yaml
nav:
  - "*.md"
```

--------------------------------

### Deep Glob for Flattening Subdirectories

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Use the '**/*.md' deep glob pattern to flatten all markdown files from all subdirectories into the navigation.

```yaml
# docs/.nav.yml

# --- Deep glob: flatten all pages from all subdirectories ---
nav:
  - "**/*.md"
```

--------------------------------

### Ignore Files Matching a Pattern

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Use the 'ignore' option to exclude files or directories matching specific patterns from the navigation. Multiple patterns can be provided in a list.

```yaml
# docs/.nav.yml — hide files matching a pattern
ignore: "*.hidden.md"

# Multiple patterns
ignore:
  - "*.hidden.md"
  - hidden/
  - internal/

# Extend inherited ignore patterns instead of replacing them
ignore:
  - $inherit
  - "*.draft.md"
```

--------------------------------

### Match All Markdown Files Recursively

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Use the `**/*.md` pattern to recursively match all files ending with `.md` in the current directory and all subdirectories.

```yaml
nav:
  - "**/*.md"
```

--------------------------------

### Natural Sort Type

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Enable natural sorting for correct numerical ordering of versioned files (e.g., version-9.1.md before version-10.0.md).

```yaml
# docs/.nav.yml

# --- Natural sort (default) handles numbers correctly ---
# version-9.0.md → version-9.1.md → version-10.0.md
sort:
  type: natural
```

--------------------------------

### Hide Entire Directory from Navigation

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Use the 'hide: true' option in a directory's .nav.yml file to exclude that entire directory from the navigation.

```yaml
# docs/api/.nav.yml — hide entire directory from navigation
hide: true
```

--------------------------------

### Mix Sections and Pages

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

Use `sort.sections: mixed` to intersperse sections with pages in the navigation. The exact order depends on the sorting of individual items.

```yaml
sort:
  sections: mixed
```

--------------------------------

### Configure Sorting by Title in .nav.yml

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

Use this configuration in your .nav.yml file to sort navigation items alphabetically by their titles. Without explicit titles in markdown files, sorting will fall back to using filenames.

```yaml
sort:
  by: title
```

--------------------------------

### Append Unmatched Files

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Set `append_unmatched: true` to automatically include files not explicitly listed in `nav` at the end. This is equivalent to adding `"*"` to your `nav` configuration.

```yaml
# docs/.nav.yml
append_unmatched: true
nav:
  - getting-started.md
  - guides
# support.md is not in nav, but gets appended automatically
# Result: Getting started → Guides (Authentication, Error handling) → Support
```

--------------------------------

### Case-Insensitive Alphabetical Sort

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Configure alphabetical sorting to ignore case for a more consistent ordering of titles.

```yaml
# docs/.nav.yml

# --- Case-insensitive alphabetical sort ---
sort:
  type: alphabetical
  ignore_case: true
```

--------------------------------

### Sorting Sections Order

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Define the order of sections relative to pages using the 'sections' option: 'first', 'mixed', or 'last'.

```yaml
# docs/.nav.yml

# --- Sort sections before pages ---
sort:
  sections: first   # first | mixed | last (default)
```

--------------------------------

### Use index.md Title as Section Title

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Set 'use_index_title: true' in a directory's .nav.yml to use the 'title' from its index.md frontmatter as the section title.

```yaml
# docs/user-guide/.nav.yml — use index.md title as section title
use_index_title: true
```

--------------------------------

### Use Index.md Title: true

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/titles.md

Set 'use_index_title: true' in .nav.yml to use the 'title' from the frontmatter of index.md as the directory navigation title. This takes precedence over directory names but is overridden by custom titles in .nav.yml or parent nav configurations.

```yaml
use_index_title: true
```

```yaml
---
title: User Guide Documentation
---
# User Guide

Welcome to the user guide!
```

--------------------------------

### Flatten Single Child Sections

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Enable 'flatten_single_child_sections: true' to automatically collapse directory sections that contain only one navigable page.

```yaml
# docs/.nav.yml
flatten_single_child_sections: true
# Before: Architecture → Architecture
# After:  Architecture  (section removed, page promoted)
```

--------------------------------

### Extend Inherited Ignore Patterns in .nav.yml

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/hiding.md

Use the special `$inherit` value within the `ignore` list to keep existing ignore patterns and add new ones.

```yaml
ignore:
  - $inherit
  - "*.hidden.md"
```

--------------------------------

### Match Files with a Specific Suffix

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/nav.md

Use patterns like `*.public.md` to match files that have a specific suffix before the `.md` extension.

```yaml
nav:
  - "*.public.md"
```

--------------------------------

### Set Sort Direction to Ascending (Default)

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

Use `sort.direction: asc` to sort pages and sections in ascending order. This is the default behavior.

```yaml
sort:
  direction: asc
```

--------------------------------

### Sorting Direction Configuration

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Control the sorting order of navigation items using the 'direction' option, which can be set to 'asc' or 'desc'.

```yaml
# docs/.nav.yml

# --- Sort direction ---
sort:
  direction: desc   # asc (default) | desc
```

--------------------------------

### Glob Pattern for Markdown Files Only

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Filter glob patterns to include only markdown files by specifying the '*.md' extension.

```yaml
# docs/.nav.yml

# --- Only markdown files (no subdirectories) ---
nav:
  - "*.md"
```

--------------------------------

### Custom Section Title in .nav.yml

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Set a custom title for a directory's section by using the 'title' key in its .nav.yml file.

```yaml
# docs/api/.nav.yml — custom title for this directory's section
title: API Endpoints
```

--------------------------------

### Use Natural Sorting (Default)

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

The default `sort.type: natural` uses natural sort order, which correctly handles numbers within strings (e.g., version numbers).

```yaml
sort:
  type: natural
```

--------------------------------

### Preserve Exact Directory Names

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Set 'preserve_directory_names: true' to use the exact directory name as the section title, preventing auto-formatting.

```yaml
# docs/.nav.yml — preserve exact directory name (no auto-formatting)
preserve_directory_names: true
# directory "awesome-nav" → section title "awesome-nav"  (not "Awesome nav")
```

--------------------------------

### Enable Case-Insensitive Alphabetical Sorting

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

Combine `sort.ignore_case: true` with `sort.type: alphabetical` for case-insensitive sorting. Note that natural sorting already groups cases together.

```yaml
sort:
  ignore_case: true
  type: alphabetical
```

--------------------------------

### Preserve Directory Names: false (default)

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/titles.md

When 'preserve_directory_names' is false or not set, directory names are automatically formatted into titles. This is the default behavior.

```yaml
preserve_directory_names: false
```

--------------------------------

### Index.md Frontmatter Title

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Define the 'title' in the frontmatter of an index.md file to be used as the section title when 'use_index_title: true' is set.

```markdown
# docs/user-guide/index.md — frontmatter title used when use_index_title: true
---
title: User Guide Documentation
---
# User Guide

Welcome!
```

--------------------------------

### Add Title to Markdown Front Matter

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

To ensure pages are sorted correctly by title, add a 'title' field to the YAML front matter at the beginning of your markdown files. This is necessary because MkDocs Awesome Nav cannot access the markdown title during the sorting phase.

```yaml
---
title: Getting started
---
```

--------------------------------

### Preserve Directory Names: true

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/titles.md

Enable 'preserve_directory_names: true' in .nav.yml to use the exact directory name as the navigation title. This setting applies to all child directories unless overridden.

```yaml
preserve_directory_names: true
```

--------------------------------

### Use Alphabetical Sorting

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

Set `sort.type: alphabetical` for strict alphabetical sorting. This is useful when natural sorting might group numbers unexpectedly.

```yaml
sort:
  type: alphabetical
```

--------------------------------

### Alphabetical Sort Type

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Use alphabetical sorting for navigation items. Note that this can lead to unexpected orderings with numbers (e.g., version-10.0.md before version-9.0.md).

```yaml
# docs/.nav.yml

# --- Alphabetical sort ---
# version-10.0.md → version-9.0.md → version-9.1.md
sort:
  type: alphabetical
```

--------------------------------

### Disable Case-Insensitive Sorting (Default)

Source: https://github.com/lukasgeiter/mkdocs-awesome-nav/blob/main/docs/features/sorting.md

Set `sort.ignore_case: false` for case-sensitive sorting when using `sort.type: alphabetical`. This is the default behavior.

```yaml
sort:
  ignore_case: false
  type: alphabetical
```

--------------------------------

### Override Parent Nav Title

Source: https://context7.com/lukasgeiter/mkdocs-awesome-nav/llms.txt

Override a section's title defined in a parent's 'nav' entry. This takes precedence over the child's .nav.yml title.

```yaml
# docs/.nav.yml — override title from parent nav (takes precedence over title in child .nav.yml)
nav:
  - REST API: api
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.