MkDocs Material Documentation

Key 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

Common Use Cases

• 1Software project documentation with API references, user guides, and developer onboarding materials
• 2Technical writing portfolios showcasing expertise in documentation tools and modern web technologies
• 3Internal company knowledge bases requiring search functionality and mobile-responsive design
• 4Open-source project documentation with contributor guidelines, installation instructions, and examples
• 5Educational content and tutorials with code examples, diagrams, and interactive elements
• 6Product documentation sites that need professional appearance without content management overhead
• 7Documentation-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

1services: 
2  mkdocs: 
3    image: squidfunk/mkdocs-material:latest
4    ports: 
5      - "8000:8000"
6    volumes: 
7      - ./docs:/docs
8    command: serve --dev-addr=0.0.0.0:8000
9    networks: 
10      - docs_net
11
12  mkdocs-build: 
13    image: squidfunk/mkdocs-material:latest
14    volumes: 
15      - ./docs:/docs
16      - ./site:/docs/site
17    command: build
18    profiles: 
19      - build
20    networks: 
21      - docs_net
22
23  nginx: 
24    image: nginx:alpine
25    ports: 
26      - "80:80"
27    volumes: 
28      - ./site:/usr/share/nginx/html:ro
29    profiles: 
30      - production
31    networks: 
32      - docs_net
33
34networks: 
35  docs_net: 

.env Template

1# MkDocs Material
2# Dev server at http://localhost:8000
3# Build with: docker compose --profile build up
4# Production with: docker compose --profile production up

Usage Notes

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

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

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  mkdocs:
5    image: squidfunk/mkdocs-material:latest
6    ports:
7      - "8000:8000"
8    volumes:
9      - ./docs:/docs
10    command: serve --dev-addr=0.0.0.0:8000
11    networks:
12      - docs_net
13
14  mkdocs-build:
15    image: squidfunk/mkdocs-material:latest
16    volumes:
17      - ./docs:/docs
18      - ./site:/docs/site
19    command: build
20    profiles:
21      - build
22    networks:
23      - docs_net
24
25  nginx:
26    image: nginx:alpine
27    ports:
28      - "80:80"
29    volumes:
30      - ./site:/usr/share/nginx/html:ro
31    profiles:
32      - production
33    networks:
34      - docs_net
35
36networks:
37  docs_net:
38EOF
39
40# 2. Create the .env file
41cat > .env << 'EOF'
42# MkDocs Material
43# Dev server at http://localhost:8000
44# Build with: docker compose --profile build up
45# Production with: docker compose --profile production up
46EOF
47
48# 3. Start the services
49docker compose up -d
50
51# 4. View logs
52docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

1curl -fsSL https://docker.recipes/api/recipes/mkdocs-material/run | bash

Troubleshooting