How to Fix MkDocs Navigation Configuration

In this tutorial, you'll learn about How to Fix MkDocs Navigation Configuration. We cover key concepts, practical examples, and best practices.

Your MkDocs site shows pages alphabetically instead of your custom order, or the navigation sidebar is empty. The nav configuration in mkdocs.yml needs attention.

The Wrong Way

# mkdocs.yml without nav section
site_name: My Docs

Without a nav section, MkDocs auto-generates navigation alphabetically — not useful for structured documentation.

The Right Way

Step 1: Define navigation structure

# mkdocs.yml
nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Configuration: getting-started/configuration.md
  - API Reference:
    - Authentication: api/auth.md
    - Endpoints: api/endpoints.md
  - About: about.md

Step 2: Match file paths exactly

# Each item maps to a file relative to docs_dir (default: docs/)
# Correct: getting-started/installation.md
# File exists at: docs/getting-started/installation.md
#
# Wrong: getting-started/installation (missing .md)
# Wrong: installation (wrong path)

Step 3: Use nested sections for organization

nav:
  - User Guide:
    - Basics:
      - Overview: user-guide/basics/overview.md
      - Quickstart: user-guide/basics/quickstart.md
    - Advanced:
      - Features: user-guide/advanced/features.md

Step 4: Handle external links in nav

nav:
  - Home: index.md
  - Documentation: https://docs.example.com  # external link
  - GitHub: https://github.com/example/repo

Navigation renders: 4 top-level items, 2 nested sections, all links working, order matches mkdocs.yml.

Prevention

• Always define the nav section explicitly — never rely on auto-generation for production sites.
• Keep the nav structure shallow (max 3 levels) for usability.
• The navigation hierarchy concept is shared by Doda Browser's folder structure — organized nesting beats flat lists every time.

Common Mistakes with nav config

1. Using foldl instead of foldl' causing stack overflow on large lists
2. Forgetting deriving (Show, Eq) on custom data types needed for debugging
3. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable

These mistakes appear frequently in real-world MKDOCS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ