# MkDocs Material Documentation

> Beautiful documentation with MkDocs Material theme and plugins.

- Category: Development Tools
- Difficulty: beginner
- Components: mkdocs, nginx
- Tags: mkdocs, documentation, material, python, markdown
- Source: https://docker.recipes/development/mkdocs-material

## Overview

MkDocs is a fast, simple static site generator specifically designed for building project documentation from Markdown files. Created by Tom Christie in 2014, MkDocs follows the philosophy that documentation should be easy to write, maintain, and deploy. The Material theme, developed by Martin Donath, transforms MkDocs into a modern documentation platform with Google's Material Design principles, offering advanced features like instant search, navigation tabs, and responsive layouts that rival commercial documentation platforms.

This stack combines the MkDocs Material theme with NGINX to create a complete documentation pipeline. During development, MkDocs runs its built-in development server with live reload capabilities, automatically rebuilding pages as you edit Markdown files. For production deployment, the build service compiles your documentation into static HTML files, which NGINX then serves with optimal performance and caching. This separation allows for rapid iteration during content creation while ensuring production-grade performance for end users.

This configuration is ideal for software teams, open-source maintainers, and technical writers who need professional documentation without the complexity of headless CMS systems or wiki platforms. The Material theme provides enterprise-grade features like multi-language support, version switching, and advanced search capabilities, while maintaining the simplicity of Markdown authoring. The combination of MkDocs' Python-based ecosystem with NGINX's proven web serving capabilities creates a documentation platform that scales from personal projects to large enterprise deployments.

## Features

- Material Design 3 theme with customizable color schemes, typography, and navigation patterns
- Instant client-side search powered by lunr.js with result highlighting and keyboard navigation
- Live reload development server that automatically rebuilds and refreshes pages on Markdown changes
- Built-in support for code syntax highlighting with over 200 programming languages via Pygments
- Navigation tabs, sections, and automatic table of contents generation with anchor linking
- Social cards generation for improved link previews on platforms like GitHub, Slack, and Twitter
- Mermaid diagram integration for flowcharts, sequence diagrams, and architectural documentation
- Plugin ecosystem including git revision dates, PDF export, and multi-language internationalization

## Use cases

- Software project documentation with API references, user guides, and developer onboarding materials
- Technical writing portfolios showcasing expertise in documentation tools and modern web technologies
- Internal company knowledge bases requiring search functionality and mobile-responsive design
- Open-source project documentation with contributor guidelines, installation instructions, and examples
- Educational content and tutorials with code examples, diagrams, and interactive elements
- Product documentation sites that need professional appearance without content management overhead
- Documentation-as-code workflows integrated with Git repositories and CI/CD pipelines

## Prerequisites

- Docker Engine 20.10+ and Docker Compose v2 for container orchestration and service management
- Minimum 512MB RAM for MkDocs build processes and NGINX static file serving
- Port 8000 available for development server and port 80 for production NGINX deployment
- Basic understanding of Markdown syntax and YAML configuration for mkdocs.yml setup
- Familiarity with directory structure conventions for organizing documentation source files
- Git knowledge recommended for version control and documentation-as-code workflows

## docker-compose.yml

```yaml
services:
  mkdocs:
    image: squidfunk/mkdocs-material:latest
    ports:
      - "8000:8000"
    volumes:
      - ./docs:/docs
    command: serve --dev-addr=0.0.0.0:8000
    networks:
      - docs_net

  mkdocs-build:
    image: squidfunk/mkdocs-material:latest
    volumes:
      - ./docs:/docs
      - ./site:/docs/site
    command: build
    profiles:
      - build
    networks:
      - docs_net

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro
    profiles:
      - production
    networks:
      - docs_net

networks:
  docs_net:
```

## .env

```bash
# MkDocs Material
# Dev server at http://localhost:8000
# Build with: docker compose --profile build up
# Production with: docker compose --profile production up
```

## Usage notes

- Dev server at http://localhost:8000
- Live reload on changes
- Material theme included
- Search, tabs, versioning
- Extensive plugin ecosystem

## Troubleshooting

- Build fails with 'Config file not found': Create mkdocs.yml in the ./docs directory with site_name and theme configuration
- Development server shows 'Permission denied' on port 8000: Check if port is already in use or run with different port mapping
- Material theme not loading properly: Verify mkdocs.yml contains 'theme: name: material' and image includes latest Material extensions
- NGINX shows 403 Forbidden on production: Ensure ./site directory exists and contains built files from mkdocs build command
- Search functionality not working: Enable search plugin in mkdocs.yml plugins section and rebuild the site
- Live reload not triggering on file changes: Verify ./docs volume mount path matches your local documentation directory structure

