mkdocs

MkDocs Documentation Site Generator

MkDocs is a fast, simple static site generator for building project documentation from Markdown files. Configuration uses a single YAML file (mkdocs.yml).

Quick Start

Installation

# Install MkDocs
pip install mkdocs

# Verify installation
mkdocs --version

Create New Project

# Create project structure
mkdocs new my-project
cd my-project

# Start development server
mkdocs serve

Project Structure Created:

my-project/
├── mkdocs.yml      # Configuration file
└── docs/
    └── index.md    # Homepage

Minimal Configuration

# mkdocs.yml
site_name: My Project
site_url: https://example.com/
nav:
  - Home: index.md
  - About: about.md

Core Commands

Command	Purpose
mkdocs new PROJECT	Create new project
mkdocs serve	Start dev server (localhost:8000)
mkdocs build	Build static site to site/
mkdocs gh-deploy	Deploy to GitHub Pages
mkdocs get-deps	Show required packages

Common Options:

• -f, --config-file FILE - Use custom config file
• -s, --strict - Fail on warnings
• -d, --site-dir DIR - Custom output directory
• --dirty - Only rebuild changed files
• --clean - Clean output before build

Project Structure

project/
├── mkdocs.yml              # Configuration (required)
├── docs/
│   ├── index.md            # Homepage
│   ├── about.md            # Additional pages
│   ├── user-guide/
│   │   ├── index.md        # Section homepage
│   │   ├── getting-started.md
│   │   └── configuration.md
│   ├── img/                # Images
│   │   └── logo.png
│   └── css/                # Custom CSS
│       └── extra.css
└── custom_theme/           # Theme customizations (optional)
    └── main.html

Navigation Configuration

# Automatic navigation (alphabetically sorted)
# Omit nav key to auto-generate

# Explicit navigation with sections
nav:
  - Home: index.md
  - User Guide:
      - Getting Started: user-guide/getting-started.md
      - Configuration: user-guide/configuration.md
  - API Reference: api/
  - External Link: https://example.com/