MkDocs Awesome Pages Plugin Guide

A practical guide for configuring MkDocs with the awesome-pages plugin based on real-world implementation experience.

Overview

The awesome-pages plugin simplifies MkDocs navigation by auto-discovering your file structure and creating navigation automatically. The key insight: less configuration is better - let the plugin do the work for you.

Key Principles

1. Use ... in mkdocs.yml nav section

The main mkdocs.yml must use the rest operator (...) to let awesome-pages take control:

nav:
  - ...

❌ Don't do this - Defining complete navigation in mkdocs.yml prevents awesome-pages from working:

nav:
  - Home: index.md
  - Getting Started:
    - Overview: getting-started/overview.md
    - Setup: getting-started/setup.md
  # ... more manual entries

2. Minimal .pages files for basic control

Use .pages files sparingly and keep them simple:

Root level: /docs/.pages (optional)

nav:
  - index.md
  - getting-started
  - trades  
  - guides
  - log
  - reference
  - about.md

Directory level: /docs/guides/.pages (minimal approach)

title: Guides
nav:
  - index.md  # Show overview first
  - ...       # Auto-discover everything else

⚠️ Avoid complex nested structures - they often cause path resolution issues.

3. Let Auto-Discovery Work

The plugin automatically: - Converts directory names to navigation sections (e.g., architecture/ → "Architecture") - Uses index.md as the landing page for directories - Alphabetically orders files and directories by default - Follows file structure to create logical hierarchy

Working Configuration Examples

Minimal Approach (Recommended)

docs/
├── .pages                 # Optional: basic order control
├── index.md
├── about.md
├── getting-started/
│   ├── index.md          # Landing page (auto-discovered)
│   ├── overview.md       # Auto-discovered
│   └── setup.md          # Auto-discovered
└── guides/
    ├── .pages            # Optional: show overview first
    ├── index.md          # Overview page
    ├── architecture/     # Auto-discovered as "Architecture"
    │   ├── index.md      # Architecture overview
    │   ├── phase-1.md    # Auto-discovered
    │   └── phase-2.md    # Auto-discovered
    └── data-analysis.md  # Auto-discovered

Minimal .pages Files

# docs/.pages (optional - only if you want specific order)
nav:
  - index.md
  - getting-started
  - guides
  - about.md

# docs/guides/.pages (optional - only to show overview first)
title: Guides  
nav:
  - index.md  # Overview first
  - ...       # Everything else auto-discovered

What You DON'T Need

# ❌ Don't manually list everything
nav:
  - Architecture:
    - Overview: architecture/index.md
    - Phase 1: architecture/phase-1-experiment.md
    - Phase 2: architecture/phase-2-productionalize.md
    # This is too complex and causes path issues!

Common Issues and Solutions

Issue: "Pages exist but are not included in nav configuration"

Symptom: MkDocs warns about pages not being included.

Root Cause: Too much configuration! Over-defining .pages files prevents auto-discovery.

Solution: 1. Simplify or remove most .pages files 2. Let awesome-pages auto-discover your content 3. Only use .pages files when you need specific ordering

Issue: Broken navigation links (404 errors)

Symptom: Navigation links point to wrong URLs (e.g., /architecture/ instead of /guides/architecture/).

Root Cause: Complex nested navigation in .pages files causes path resolution conflicts.

Solution: 1. Remove complex .pages files in subdirectories 2. Use simple directory references: - architecture not - Architecture: architecture/ 3. Let the plugin handle path resolution automatically

Issue: "Absolute path to '/...' is included in nav"

Symptom: Warning about absolute paths in navigation.

Cause: The ... rest operator in .pages files.

Solution: This is expected behavior - the warning can be safely ignored.

Plugin Configuration

Enable the plugin in mkdocs.yml:

plugins:
  - search
  - awesome-pages

Optional configuration:

plugins:
  - awesome-pages:
      filename: .pages           # Default: .pages
      collapse_single_pages: true # Collapse single-item directories
      strict: false              # Don't fail on missing files

Best Practices

1. Start with No Configuration

Let awesome-pages auto-discover everything first. Only add .pages files if you need specific ordering.

2. Use index.md for Directory Landing Pages

Create index.md files in directories to provide overview pages:

guides/
├── index.md          # Guides overview
├── architecture/
│   ├── index.md      # Architecture overview  
│   ├── phase-1.md
│   └── phase-2.md

3. Keep .pages Files Minimal

When you do need .pages files, keep them simple:

title: Section Name
nav:
  - index.md  # Overview first
  - ...       # Auto-discover the rest

4. Trust Auto-Discovery

The plugin is smart about: - Converting filenames to readable titles - Organizing content logically - Creating proper URL paths

5. Test Locally

Always test with mkdocs serve to catch issues early.

Migration from Manual Navigation

If migrating from manual mkdocs.yml navigation:

1. Save your current nav structure - document the intended hierarchy
2. Replace nav with ... in mkdocs.yml
3. Create root .pages with simple directory/file references
4. Create directory .pages files for each section
5. Test and iterate until navigation matches your intended structure

Troubleshooting

Debug Navigation Issues

1. Check MkDocs build output - warnings often indicate the exact issue
2. Verify file paths - ensure all referenced files exist
3. Test incrementally - start with basic structure and add complexity
4. Use MkDocs serve - live reload helps identify issues quickly

Common File Path Issues

# ❌ Wrong - file doesn't exist
nav:
  - Guide: guide.md

# ✅ Correct - file exists at this path  
nav:
  - Guide: data-analysis.md

Validation Checklist

• mkdocs.yml uses nav: - ...
• Root .pages file exists with basic structure
• All referenced files/directories exist
• Directory .pages files have title and nav sections
• File paths are relative to the directory containing the .pages file
• No duplicate entries across .pages files

Conclusion

The awesome-pages plugin works best when you embrace auto-discovery:

1. Less is more - minimal configuration works better than complex .pages files
2. Trust the plugin - it's designed to organize content intelligently
3. Use index.md files - provide overview pages for directories
4. Test locally - catch issues early with mkdocs serve

Key Insight: The plugin's strength is auto-discovery. Fighting it with complex configuration causes more problems than it solves.

This minimal approach scales excellently for large documentation sites and requires almost no maintenance.