mkdocs

mkdocs Best Practices

This guide establishes the definitive standards for writing and maintaining documentation using MkDocs, especially with the Material for MkDocs theme. Adhere to these rules to ensure consistency, readability, and maintainability across all our projects.

1. Code Organization & Structure

Always organize your documentation for logical navigation and maintainability.

1.1 Root Structure

Place mkdocs.yml at the project root, and all Markdown source files within a top-level docs/ directory. The homepage must be index.md.

❌ BAD:

my-project/
├── docs/
│   ├── mkdocs.yml  # mkdocs.yml should be at project root
│   └── homepage.md # Homepage should be index.md

✅ GOOD:

my-project/
├── mkdocs.yml
└── docs/
    ├── index.md
    └── user-guide/
        └── getting-started.md

1.2 Navigation Ordering

Control navigation explicitly using the mkdocs-awesome-pages-plugin and .pages files. Never rely on default alphabetical ordering.

❌ BAD:

# mkdocs.yml
nav:
  - Home: index.md
  - API: api.md
  - Setup: setup.md # Order is alphabetical, not logical

✅ GOOD:

# docs/.pages
nav:
  - Home: index.md
  - Setup: setup.md
  - API: api.md
  - ... # Include remaining pages automatically

2. Markdown Style & Content

Enforce a strict Markdown style for readability and consistency, ideally with markdownlint.

2.1 Headings Hierarchy

Use a single H1 (#) per page for the main title. Subsequent headings must follow a strict, sequential hierarchy (H2, H3, etc.). Never skip heading levels.

❌ BAD:

# My Page Title
### A Sub-section # Skipped H2

✅ GOOD:

# My Page Title
## Introduction
### Key Concepts

2.2 Line Length

Limit text lines to 80 characters for improved readability and diffs. Exceptions are allowed for long URLs, tables, and code blocks.

❌ BAD:

This is a very long line of text that exceeds eighty characters and makes it difficult to read and review, especially in side-by-side diffs.