MkDocs
Python-based documentation-focused SSG. Over 18k GitHub stars, specialized for Markdown-based documentation creation.
トレンド・動向
Popular for API specification and technical documentation creation. Easy creation of beautiful documentation with Material for MkDocs theme.
# Static Site Generator
MkDocs
## Overview
MkDocs has been developed since 2014 as a Python-based documentation-focused SSG, boasting over 18k GitHub stars as a tool specialized for Markdown-based technical documentation creation. With simple configuration and clean Markdown syntax, it makes creating API specifications, technical documentation, and project manuals easy. The beautiful appearance through Material for MkDocs theme, search functionality, and versioning support make it widely adopted from open source projects to enterprise technical documentation.
## Details
MkDocs 2025 edition is established as the de facto standard for technical documentation creation, providing a developer-friendly environment through its affinity with the Python ecosystem. It features simple configuration management through YAML config files, flexible customization via Jinja2 template engine, and functionality extension through a rich plugin ecosystem. Particularly, the Material for MkDocs theme easily builds modern technical documentation sites with beautiful UI adopting Google's Material Design, advanced search functionality, dark mode support, and responsive design.
### Key Features
- **Documentation-Focused Design**: Optimized for API specifications, technical manuals, and tutorials
- **Material for MkDocs Theme**: Beautiful UI based on Google Material Design
- **Powerful Search Functionality**: Indexed high-speed search with highlight display
- **Versioning Support**: Multiple version documentation management
- **Plugin Ecosystem**: Rich Python-based functionality extensions
- **Live Reload**: Efficient editing with real-time preview
- **Multi-language Support**: Internationalization support through i18n plugin
## Pros and Cons
### Pros
- Intuitive documentation creation with simple Markdown syntax and YAML configuration
- Professional and beautiful appearance through Material for MkDocs theme
- High-speed search functionality and excellent usability navigation
- Development workflow efficiency through Python ecosystem integration
- Large-scale project support through versioning and multi-language support
- Automatic deployment through GitHub Actions and CI/CD integration
- Rich functionality extension and customization through plugins
### Cons
- Python environment required with limited compatibility with Ruby or Node.js environments
- Basically no blog functionality, unsuitable for uses other than technical documentation
- Build speed for large sites inferior compared to Hugo or Zola
- Limited theme choices compared to Jekyll or Hugo
- Complex layout customization requires Python/Jinja2 knowledge
- Feature shortage for general website construction due to documentation focus
## Reference Pages
- [MkDocs Official Site](https://www.mkdocs.org/)
- [MkDocs GitHub Repository](https://github.com/mkdocs/mkdocs)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
## Code Examples
### Installation and Project Creation
```bash
# Check Python and pip
python3 --version
pip3 --version
# Install MkDocs
pip install mkdocs
# Install Material for MkDocs theme (recommended)
pip install mkdocs-material
# Create new project
mkdocs new my-project
cd my-project
# Check project structure
ls -la
# mkdocs.yml (configuration file)
# docs/ (documentation directory)
# index.md (homepage)
# Start development server
mkdocs serve
# => Available at http://127.0.0.1:8000
# Start with specific port/host
mkdocs serve --dev-addr=127.0.0.1:8080
# Start in debug mode
mkdocs serve --verbose
```
### Basic Configuration File Setup
```yaml
# mkdocs.yml - Basic configuration
site_name: My Technical Documentation
site_description: Comprehensive technical documentation site
site_author: Your Name
site_url: https://your-domain.com
# Repository settings
repo_name: username/my-project
repo_url: https://github.com/username/my-project
edit_uri: edit/main/docs/
# Theme settings (using Material for MkDocs)
theme:
name: material
language: en
palette:
# Light mode
- scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/brightness-7
name: Switch to dark mode
# Dark mode
- scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/brightness-4
name: Switch to light mode
features:
- navigation.instant
- navigation.tracking
- navigation.tabs
- navigation.sections
- navigation.expand
- navigation.top
- search.suggest
- search.highlight
- search.share
- content.code.annotate
- content.code.copy
icon:
repo: fontawesome/brands/github
# Navigation structure
nav:
- Home: index.md
- Getting Started:
- Installation: getting-started/installation.md
- Quick Start: getting-started/quickstart.md
- API Reference:
- Authentication: api/authentication.md
- Endpoints: api/endpoints.md
- Guides:
- Best Practices: guides/best-practices.md
- Troubleshooting: guides/troubleshooting.md
- Release Notes: changelog.md
# Markdown extensions
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
custom_checkbox: true
- attr_list
- md_in_html
- toc:
permalink: true
# Plugin configuration
plugins:
- search:
lang: en
- git-revision-date-localized:
type: date
# Additional CSS & JavaScript
extra_css:
- stylesheets/extra.css
extra_javascript:
- javascripts/extra.js
# Custom variables
extra:
version: 1.0.0
social:
- icon: fontawesome/brands/github
link: https://github.com/username
- icon: fontawesome/brands/twitter
link: https://twitter.com/username
```
### Creating Documentation Content
```markdown
<!-- docs/index.md -->
# Project Overview
This site is a comprehensive guide for technical documentation.
## Features
!!! info "Important Information"
This project requires Python 3.8 or higher.
### Key Features
- [x] High-speed API processing
- [x] Secure authentication system
- [ ] Multi-language support (in development)
## Installation
```bash
pip install my-project
```
### Basic Usage
```python
import my_project
# Initialize client
client = my_project.Client(api_key="your-api-key")
# Get data
data = client.get_data()
print(data)
```
## Code Examples
=== "Python"
```python
def hello_world():
return "Hello, World!"
print(hello_world())
```
=== "JavaScript"
```javascript
function helloWorld() {
return "Hello, World!";
}
console.log(helloWorld());
```
=== "Bash"
```bash
#!/bin/bash
echo "Hello, World!"
```
## Next Steps
1. Check the [Installation Guide](getting-started/installation.md)
2. Start with [Quick Start](getting-started/quickstart.md)
3. Learn details in [API Reference](api/authentication.md)
---
<!-- docs/api/authentication.md -->
# Authentication
## Overview
API access requires authentication via API key.
!!! warning "Security Notice"
Please manage API keys as confidential information properly.
## Getting API Key
1. Access [Developer Portal](https://dev.example.com)
2. Create account or login
3. Generate new API key
## Authentication Methods
### Header Authentication
```http
GET /api/v1/data HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```
### Query Parameter Authentication
```http
GET /api/v1/data?api_key=YOUR_API_KEY HTTP/1.1
Host: api.example.com
```
## Error Handling
| Status Code | Description | Solution |
|-------------|-------------|----------|
| 401 | Authentication Error | Check API key |
| 403 | Insufficient Permissions | Check access permissions |
| 429 | Rate Limit | Wait and retry |
!!! example "Authentication Example"
```python
import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
response = requests.get(
'https://api.example.com/v1/data',
headers=headers
)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
```
```
### Theme Customization and Styling
```yaml
# mkdocs.yml - Advanced theme configuration
theme:
name: material
language: en
# Custom directory (for overrides)
custom_dir: overrides/
# Color palette configuration
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
primary: blue
accent: blue
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: blue
accent: blue
toggle:
icon: material/brightness-4
name: Switch to light mode
# Font configuration
font:
text: Roboto
code: Roboto Mono
# Favicon
favicon: assets/favicon.png
# Logo
logo: assets/logo.png
# Feature configuration
features:
- announce.dismiss
- content.action.edit
- content.action.view
- content.code.annotate
- content.code.copy
- content.code.select
- content.tooltips
- navigation.footer
- navigation.indexes
- navigation.instant
- navigation.instant.prefetch
- navigation.instant.progress
- navigation.path
- navigation.prune
- navigation.sections
- navigation.tabs
- navigation.tabs.sticky
- navigation.top
- navigation.tracking
- search.highlight
- search.share
- search.suggest
- toc.follow
```
```css
/* docs/stylesheets/extra.css */
:root {
--md-primary-fg-color: #1976d2;
--md-primary-fg-color--light: #42a5f5;
--md-primary-fg-color--dark: #1565c0;
--md-accent-fg-color: #ff4081;
}
/* Custom admonitions */
.md-typeset .admonition.custom,
.md-typeset details.custom {
border-color: #448aff;
}
.md-typeset .custom > .admonition-title,
.md-typeset .custom > summary {
background-color: #448aff1a;
border-color: #448aff;
}
.md-typeset .custom > .admonition-title::before,
.md-typeset .custom > summary::before {
background-color: #448aff;
mask-image: var(--md-admonition-icon--note);
}
/* Code block customization */
.md-typeset .highlight pre {
border-radius: 0.2rem;
}
/* Navigation adjustments */
.md-nav__title {
font-weight: 700;
}
/* Footer customization */
.md-footer {
background-color: var(--md-footer-bg-color);
}
/* Responsive adjustments */
@media screen and (max-width: 76.1875em) {
.md-nav--primary .md-nav__title {
background-color: var(--md-primary-fg-color);
}
}
```
### Plugin Configuration and Feature Extensions
```yaml
# mkdocs.yml - Plugin configuration
plugins:
# Search functionality
- search:
lang:
- en
- ja
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
# Git information plugin
- git-revision-date-localized:
enable_creation_date: true
type: timeago
timezone: UTC
locale: en
# Git author information
- git-authors:
show_contribution: true
show_line_count: true
count_empty_lines: false
# Mermaid diagrams
- mermaid2:
arguments:
theme: neutral
# Tags functionality
- tags:
tags_file: tags.md
# Macro functionality
- macros:
include_dir: docs/includes
# PDF export
- pdf-export:
verbose: true
media_type: print
enabled_if_env: ENABLE_PDF_EXPORT
# API documentation generation
- mkdocstrings:
handlers:
python:
options:
docstring_style: google
show_source: true
# Multi-language support
- i18n:
default_language: en
languages:
en:
name: English
build: true
ja:
name: 日本語
build: true
nav_translations:
ja:
Home: ホーム
Getting Started: 導入
API Reference: APIリファレンス
Guides: ガイド
Release Notes: リリースノート
# Markdown extensions detailed configuration
markdown_extensions:
# Metadata
- meta
# Table of contents
- toc:
permalink: true
baselevel: 1
separator: "_"
# Admonitions
- admonition
- pymdownx.details
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
# Code highlighting
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets:
check_paths: true
# Tabs
- pymdownx.tabbed:
alternate_style: true
# Task lists
- pymdownx.tasklist:
custom_checkbox: true
# Math
- pymdownx.arithmatex:
generic: true
# Emoji
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
# Abbreviations
- abbr
# Definition lists
- def_list
# HTML attributes
- attr_list
- md_in_html
# Footnotes
- footnotes
# Keyboard shortcuts
- pymdownx.keys
# Mark, insert, delete
- pymdownx.mark
- pymdownx.caret
- pymdownx.tilde
# SmartSymbols
- pymdownx.smartsymbols
# Additional configuration
extra:
version:
provider: mike
default: latest
analytics:
provider: google
property: G-XXXXXXXXXX
consent:
title: Cookie consent
description: >-
We use cookies to recognize your repeated visits and preferences, as well
as to measure the effectiveness of our documentation and whether users
find what they're searching for. With your consent, you're helping us to
make our documentation better.
social:
- icon: fontawesome/brands/github
link: https://github.com/username
- icon: fontawesome/brands/twitter
link: https://twitter.com/username
- icon: fontawesome/brands/linkedin
link: https://linkedin.com/in/username
generator: false
```
### Deployment and CI/CD Configuration
```yaml
# .github/workflows/docs.yml - GitHub Actions
name: Build and Deploy Documentation
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Cache pip dependencies
uses: actions/cache@v3
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install mkdocs-material
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-git-authors-plugin
pip install mkdocstrings[python]
pip install mkdocs-mermaid2-plugin
- name: Build documentation
run: |
mkdocs build --verbose --strict
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Upload artifact
uses: actions/upload-pages-artifact@v2
with:
path: './site'
deploy:
if: github.ref == 'refs/heads/main'
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
```
```bash
# Production build and deployment
# 1. Install dependencies
pip install -r requirements.txt
# requirements.txt example
cat > requirements.txt << EOF
mkdocs>=1.5.0
mkdocs-material>=9.0.0
mkdocs-git-revision-date-localized-plugin
mkdocs-git-authors-plugin
mkdocstrings[python]
mkdocs-mermaid2-plugin
pymdown-extensions
EOF
# 2. Local production build test
mkdocs build --strict --verbose
# 3. Check site
ls -la site/
find site -name "*.html" | head -5
# 4. GitHub Pages deployment
mkdocs gh-deploy --force
# 5. Custom server deployment
mkdocs build
rsync -avz --delete site/ [email protected]:/var/www/docs/
# 6. Docker build
docker run --rm -v $(pwd):/docs squidfunk/mkdocs-material build
# 7. Netlify deployment configuration
# netlify.toml
cat > netlify.toml << EOF
[build]
publish = "site"
command = "pip install -r requirements.txt && mkdocs build"
[build.environment]
PYTHON_VERSION = "3.11"
EOF
# 8. Version management (using mike)
pip install mike
mike deploy --push --update-aliases 1.0 latest
mike set-default --push latest
```