A streamlined, containerized build environment for modern documentation workflows. Built on Python 3.12 Alpine, this image provides a batteries-included toolchain specifically optimized for GitHub Actions and CI/CD pipelines.
Note: This project uses a "Configuration-as-Data" approach — automatically generating
mkdocs.ymlat runtime by merging internal templates with your project metadata.
- Features
- Quick Start
- Architecture
- Usage
- Configuration
- Available Commands
- Technical Details
- Contributing
- License
| Feature | Description |
|---|---|
| 🚀 Lightweight | Built on Alpine Linux (~50MB base), ensuring rapid image pulls and minimal CI resource usage |
| 🧩 Dynamic Configuration | Auto-generates mkdocs.yml from info.json, templates, and local overrides |
| 🔋 Batteries Included | Pre-configured with essential MkDocs plugins and extensions |
| 🛠 CI/CD Optimized | Includes bash, git, nodejs, and other tools for seamless GitHub Actions integration |
| 📝 Markdown Linting | Built-in markdownlint-cli2 for automatic style enforcement |
| ⚡ Multiple Serve Modes | Standard mkdocs serve and high-performance zensical serve |
MkDocs Plugins:
mkdocs-glightbox— Image lightbox/zoomingmkdocs-minify-plugin— HTML minification for production
Markdown Extensions:
pymdown-extensions— Advanced syntax (arithmatex, highlight, snippets, etc.)- Full
mkdocs-materialfeature support (navigation, search, code copy, etc.)
# Pull the image
docker pull ghcr.io/raineblog/mkdocs-docker:latest
# Build documentation
docker run --rm -v $(pwd):/app/workspace -w /app/workspace \
ghcr.io/raineblog/mkdocs-docker:latest mkdocs-build
# Serve with live-reload
docker run --rm -it -p 8000:8000 -v $(pwd):/app/workspace -w /app/workspace \
ghcr.io/raineblog/mkdocs-docker:latest mkdocs-serveThis builder uses a "Configuration-as-Data" approach. Instead of manually maintaining a complex mkdocs.yml, the environment generates it at runtime by merging three sources:
Use this image as a job container in your workflow:
name: Build and Deploy Documentation
on:
push:
branches: [main]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
container:
image: ghcr.io/raineblog/mkdocs-docker:latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build Documentation
run: mkdocs-build
- name: Deploy to GitHub Pages
uses: actions/upload-pages-artifact@v3
with:
path: ./siteBuild documentation:
docker run --rm \
-v $(pwd):/app/workspace \
-w /app/workspace \
ghcr.io/raineblog/mkdocs-docker:latest \
mkdocs-buildServe with live-reload (Linux/macOS):
docker run --rm -it \
-v $(pwd):/app/workspace \
-w /app/workspace \
-p 8000:8000 \
ghcr.io/raineblog/mkdocs-docker:latest \
mkdocs-serveServe with live-reload (Windows PowerShell):
docker run --rm -it --init `
-v ${pwd}:/app/workspace `
-w /app/workspace `
-p 8000:8000 `
ghcr.io/raineblog/mkdocs-docker:latest `
mkdocs-serve.PHONY: serve build lint pull
IMAGE := ghcr.io/raineblog/mkdocs-docker:latest
serve:
docker run --rm -it --init -p 8000:8000 \
-v $(CURDIR):/app/workspace -w /app/workspace \
$(IMAGE) mkdocs-serve
build:
docker run --rm \
-v $(CURDIR):/app/workspace -w /app/workspace \
$(IMAGE) mkdocs-build
lint:
docker run --rm \
-v $(CURDIR):/app/workspace -w /app/workspace \
$(IMAGE) mkdocs-lint
pull:
docker pull $(IMAGE)Your project must follow this structure:
.
├── info.json # Required: Project metadata & navigation
├── docs/ # Required: Markdown content
│ ├── index.md # Required: Homepage
│ ├── intro/ # Required: Introduction section
│ │ ├── format.md
│ │ ├── usage.md
│ │ └── discussion.md
│ ├── madoka.md # Required: Part of intro
│ └── assets/ # Optional
│ └── extra.yml # Optional: MkDocs config overrides
├── includes/ # Optional: Snippets for inclusion
│ └── abbreviations.md # Optional: Abbreviation definitions
└── .markdownlint.json # Optional: Custom linting rules
Important
This builder is opinionated and automatically prepends several "Introduction" pages to your navigation. Ensure these required files exist in your docs/ folder to avoid build errors.
The info.json file is the heart of your documentation metadata:
{
"project": {
"site_name": "My Documentation",
"site_description": "A wonderful project description",
"repo_url": "https://github.com/user/repo"
},
"nav": [
{
"title": "Getting Started",
"children": [
"guide/install.md",
"guide/config.md"
]
},
{
"title": "Reference",
"children": [
"reference/api.md",
"reference/cli.md"
]
}
],
"extra": {
"version": "1.0.0",
"social": [
{ "icon": "fontawesome/brands/github", "link": "https://github.com/user" }
]
}
}| Field | Type | Description |
|---|---|---|
project |
Object | Core MkDocs settings (site_name, site_description, repo_url, etc.) |
nav |
Array | Navigation structure with title and children |
extra |
Object | Additional MkDocs extra configuration |
| Command | Description |
|---|---|
mkdocs-build |
Full build pipeline: lint → generate config → build → sync artifacts |
mkdocs-serve |
Start development server with live-reload on port 8000 |
mkdocs-lint |
Run Markdown linting with auto-fix |
zensical-serve |
Alternative high-performance server (fewer features, faster startup) |
The mkdocs-build command executes these steps:
- Lint — Run
markdownlint-cli2with auto-fix - Generate — Create
mkdocs.ymlfrom templates andinfo.json - Build — Execute
mkdocs build --strict --clean - Sync — Merge any static assets from
public/intosite/
- Python 3.12 Alpine — Minimal footprint, fast startup
- Multi-stage build to include
markdownlint-cli2from Node.js
| Package | Purpose |
|---|---|
bash |
Shell scripts execution |
git |
Version control, mkdocs-git plugins |
nodejs |
Markdown linting runtime |
ca-certificates |
HTTPS support |
pyyaml # YAML parsing
mkdocs # Static site generator
mkdocs-glightbox # Image lightbox
mkdocs-minify-plugin # HTML minification
pymdown-extensions # Markdown extensions
zensical # High-performance server
This project is a personal toolchain maintained by @raineblog.
| Type | Status |
|---|---|
| 🐛 Bug Reports | ✅ Welcome |
| 📝 Corrections | ✅ Welcome (typos, documentation fixes) |
| 🔒 Security Patches | ✅ Welcome |
| ✨ Feature Requests | ❌ Not accepting |
| 🔀 Pull Requests (new features) | ❌ Not accepting |
Why no feature requests? This tool is designed to be highly specialized for a specific workflow. If you need more flexibility or additional features, I recommend using the official squidfunk/mkdocs-material Docker image.
If you encounter a bug, please open an issue with:
- Docker version and host OS
- Command that triggered the error
- Full error output
- Minimal reproduction steps (if possible)
Distributed under the MIT License. See LICENSE for more information.
MIT License
Copyright (c) 2026 RainPPR
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...
📝 Documentation Notice: This README was generated by Antigravity (Claude Opus 4.5), an AI coding assistant developed by Google DeepMind, and has been reviewed and approved by a human maintainer.