MD074 - MkDocs nav validation¶

Aliases: mkdocs-nav

What this rule does¶

Validates that MkDocs navigation entries in mkdocs.yml point to existing files. This rule only runs when the markdown flavor is set to mkdocs.

Why this matters¶

• Prevents broken navigation: Ensures all nav entries resolve to actual documentation files
• Catches typos: Common mistakes in file paths are caught before deployment
• Maintains site structure: Helps keep your MkDocs site organized and complete

Examples¶

Given this mkdocs.yml:

site_name: My Docs
docs_dir: docs
nav:
  - Home: index.md
  - Guide: guide.md
  - API:
    - Overview: api/overview.md
    - Reference: api/reference.md

✅ Correct¶

All referenced files exist in the docs/ directory:

• docs/index.md
• docs/guide.md
• docs/api/overview.md
• docs/api/reference.md

Directory nav entries like - Section: section/ are valid if section/index.md exists.

❌ Incorrect¶

nav:
  - Home: index.md
  - Guide: missing-guide.md      # File doesn't exist
  - API:
    - Overview: /api/overview.md  # Absolute path (if configured to warn)

🔧 Fixed¶

This rule cannot automatically fix broken nav entries. You must manually:

• Fix typos in file paths
• Create missing documentation files
• Update nav structure after moving files

Configuration¶

not-found¶

How to handle nav entries pointing to non-existent files.

omitted-files¶

How to handle files in docs_dir that aren't referenced in nav.

absolute-links¶

How to handle absolute links (starting with /) in nav entries.

Example configuration¶

# .rumdl.toml
[global]
flavor = "mkdocs"

[MD074]
not-found = "warn"
omitted-files = "warn"
absolute-links = "warn"

Automatic fixes¶

This rule does not provide automatic fixes. Missing nav entries must be corrected manually.

Learn more¶

• MkDocs Navigation
• MkDocs Configuration

Related rules¶

• MD057 - Check that file links work
• MD051 - Fix broken link fragments