MkDocs Cheatsheet¶
MkDocs - Projektdokumentation mit Markdown_
MkDocs ist ein schnelles, einfaches und aufrechtes wunderschönes statisches Site-Generator, der auf die Bauprojektdokumentation ausgerichtet ist. Dokumentierungsquellendateien werden in Markdown geschrieben und mit einer einzigen YAML Konfigurationsdatei konfiguriert.
_Inhaltsverzeichnis - (#Installation) - (#getting-started) - Projektstruktur - (#configuration) - (#writing-documentation) - (Navigation) - (#Themes) - (Plugins) (#plugins) - (#Erweiterungen) - (# Bereitstellung) - Custom Themes - Erweiterte Konfiguration - Internationalisierung - (Suche) - API-Dokumentation - (#performance) - (#best-practices)
• Installation
Python Installation¶
# Install Python (if not already installed)
# MkDocs requires Python 3.7+
# Check Python version
python --version
python3 --version
```_
### Install MkDocs
```bash
# Install via pip
pip install mkdocs
# Install with additional dependencies
pip install mkdocs[i18n]
# Install specific version
pip install mkdocs==1.5.3
# Verify installation
mkdocs --version
```_
### Virtuelle Umgebung (empfohlen)
```bash
# Create virtual environment
python -m venv mkdocs-env
# Activate virtual environment
# On Windows
mkdocs-env\Scripts\activate
# On macOS/Linux
source mkdocs-env/bin/activate
# Install MkDocs
pip install mkdocs
# Deactivate when done
deactivate
```_
### Entwicklungsinstallation
```bash
# Install from source
git clone https://github.com/mkdocs/mkdocs.git
cd mkdocs
pip install -e .
# Install development dependencies
pip install -r requirements/dev.txt
```_
Gestartet
### Neues Projekt erstellen
```bash
# Create new MkDocs project
mkdocs new my-project
# Navigate to project directory
cd my-project
# Project structure created:
# my-project/
# ├── docs/
# │ └── index.md
# └── mkdocs.yml
```_
### Basic Commands
```bash
# Start development server
mkdocs serve
# Start on custom port
mkdocs serve --dev-addr=127.0.0.1:8080
# Build static site
mkdocs build
# Build and clean output directory
mkdocs build --clean
# Deploy to GitHub Pages
mkdocs gh-deploy
```_
### Erstdokumentation
```markdown
<!-- docs/index.md -->
# Welcome to My Project
This is the homepage of my documentation.
## Features
- Easy to use
- Fast and responsive
- Beautiful themes
## Getting Started
Check out the [User Guide](user-guide.md) to get started.
```_
```yaml
# mkdocs.yml
site_name: My Project Documentation
site_description: A comprehensive guide to my project
site_author: Your Name
site_url: https://yourname.github.io/my-project
nav:
- Home: index.md
- User Guide: user-guide.md
- API Reference: api.md
theme:
name: material
Projektstruktur
Grundstruktur¶
my-project/
├── docs/ # Documentation source files
│ ├── index.md # Homepage
│ ├── user-guide.md # User guide
│ ├── api.md # API documentation
│ ├── images/ # Images and assets
│ └── stylesheets/ # Custom CSS
├── mkdocs.yml # Configuration file
└── site/ # Generated site (after build)
```_
### Advanced Structure
```bash
my-project/
├── docs/
│ ├── index.md
│ ├── getting-started/
│ │ ├── index.md
│ │ ├── installation.md
│ │ └── quickstart.md
│ ├── user-guide/
│ │ ├── index.md
│ │ ├── configuration.md
│ │ └── advanced.md
│ ├── api/
│ │ ├── index.md
│ │ ├── endpoints.md
│ │ └── examples.md
│ ├── assets/
│ │ ├── images/
│ │ ├── css/
│ │ └── js/
│ └── overrides/ # Theme overrides
├── mkdocs.yml
├── requirements.txt # Python dependencies
└── .github/
└── workflows/
└── ci.yml # GitHub Actions
```_
### Mehrsprachige Struktur
```bash
my-project/
├── docs/
│ ├── en/ # English documentation
│ │ ├── index.md
│ │ └── guide.md
│ ├── es/ # Spanish documentation
│ │ ├── index.md
│ │ └── guide.md
│ └── fr/ # French documentation
│ ├── index.md
│ └── guide.md
├── mkdocs.yml
├── mkdocs.es.yml # Spanish config
└── mkdocs.fr.yml # French config
```_
Konfiguration
### Grundkonfiguration
```yaml
# mkdocs.yml
site_name: My Project
site_description: A great project
site_author: Your Name
site_url: https://example.com
# Repository
repo_name: username/repository
repo_url: https://github.com/username/repository
edit_uri: edit/main/docs/
# Copyright
copyright: Copyright © 2023 Your Name
# Navigation
nav:
- Home: index.md
- Getting Started:
- Installation: getting-started/installation.md
- Quick Start: getting-started/quickstart.md
- User Guide:
- Overview: user-guide/index.md
- Configuration: user-guide/configuration.md
- API Reference: api.md
# Theme
theme:
name: material
language: en
# Build
docs_dir: docs
site_dir: site
```_
### Erweiterte Konfiguration
```yaml
# mkdocs.yml
site_name: Advanced Project Documentation
site_description: Comprehensive documentation with advanced features
site_author: Your Name
site_url: https://docs.example.com
# Repository information
repo_name: username/project
repo_url: https://github.com/username/project
edit_uri: edit/main/docs/
# Copyright and legal
copyright: |
Copyright © 2023 <a href="https://example.com">Your Company</a><br>
Licensed under <a href="https://opensource.org/licenses/MIT">MIT License</a>
# Navigation structure
nav:
- Home: index.md
- Getting Started:
- Overview: getting-started/index.md
- Installation: getting-started/installation.md
- Quick Start: getting-started/quickstart.md
- Configuration: getting-started/configuration.md
- User Guide:
- Introduction: user-guide/index.md
- Basic Usage: user-guide/basic-usage.md
- Advanced Features: user-guide/advanced.md
- Troubleshooting: user-guide/troubleshooting.md
- API Reference:
- Overview: api/index.md
- Authentication: api/auth.md
- Endpoints: api/endpoints.md
- Examples: api/examples.md
- Development:
- Contributing: development/contributing.md
- Testing: development/testing.md
- Release Notes: development/changelog.md
# Theme configuration
theme:
name: material
language: en
palette:
- scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/brightness-7
name: Switch to dark mode
- scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/brightness-4
name: Switch to light mode
font:
text: Roboto
code: Roboto Mono
features:
- navigation.tabs
- navigation.sections
- navigation.expand
- navigation.top
- search.highlight
- search.share
- content.code.copy
# Plugins
plugins:
- search:
lang: en
- minify:
minify_html: true
- git-revision-date-localized:
type: date
# Markdown extensions
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.tabbed:
alternate_style: true
- attr_list
- md_in_html
- tables
- footnotes
- toc:
permalink: true
# Extra CSS and JavaScript
extra_css:
- stylesheets/extra.css
- stylesheets/custom.css
extra_javascript:
- javascripts/extra.js
- https://unpkg.com/mermaid@8.6.4/dist/mermaid.min.js
# Extra configuration
extra:
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
analytics:
provider: google
property: G-XXXXXXXXXX
version:
provider: mike
```_
### Umweltspezifisch Konfiguration
```yaml
# mkdocs.yml (base configuration)
site_name: My Project
docs_dir: docs
site_dir: site
# Development configuration
dev_addr: 127.0.0.1:8000
use_directory_urls: true
# Production configuration
site_url: https://docs.example.com
use_directory_urls: false
```_
Schreibdokumentation
### Markdown Basics
```markdown
# Heading 1
## Heading 2
### Heading 3
**Bold text**
*Italic text*
~~Strikethrough~~
`Inline code`
- Unordered list item 1
- Unordered list item 2
- Nested item
1. Ordered list item 1
2. Ordered list item 2
[Link text](https://example.com)
[Internal link](user-guide.md)
[Link with title](https://example.com "Title")
```_
### Code Blocks
````markdown
```python
def hello_world():
print("Hallo, Welt!")
``python Leinenums="1"
def fibonacci(n):
wenn n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
__CODE_BLOCK_18__python hl_lines="2 3"
def process_data(data):
cleaned_data = clean(data) # This line is highlighted
result = analyze(cleaned_data) # This line is highlighted
return result
__CODE_BLOCK_19__
Tables¶
CODE_BLOCK_20
Admonitions¶
CODE_BLOCK_21
Content Tabs¶
CODE_BLOCK_22__python def hello(): print("Hello from Python!") __CODE_BLOCK_23__javascript function hello() { console.log("Hello from JavaScript!"); } __CODE_BLOCK_24__bash echo "Hello from Bash!" __CODE_BLOCK_25
Footnotes¶
CODE_BLOCK_26
Navigation¶
Simple Navigation¶
CODE_BLOCK_27
Hierarchical Navigation¶
CODE_BLOCK_28
Auto-generated Navigation¶
CODE_BLOCK_29
CODE_BLOCK_30
Navigation with External Links¶
CODE_BLOCK_31
Themes¶
Material Theme¶
CODE_BLOCK_32
CODE_BLOCK_33
ReadTheDocs Theme¶
CODE_BLOCK_34
Custom Theme Configuration¶
CODE_BLOCK_35
Theme Switching¶
CODE_BLOCK_36
Plugins¶
Essential Plugins¶
CODE_BLOCK_37
Search Plugin¶
CODE_BLOCK_38
Git Revision Date Plugin¶
CODE_BLOCK_39
Minify Plugin¶
CODE_BLOCK_40
Awesome Pages Plugin¶
CODE_BLOCK_41
Redirects Plugin¶
CODE_BLOCK_42
Custom Plugin Configuration¶
CODE_BLOCK_43
Extensions¶
PyMdown Extensions¶
CODE_BLOCK_44
CODE_BLOCK_45
Code Highlighting¶
CODE_BLOCK_46
Math Support¶
CODE_BLOCK_47
CODE_BLOCK_48
Deployment¶
GitHub Pages¶
CODE_BLOCK_49
GitHub Actions¶
CODE_BLOCK_50
Netlify¶
CODE_BLOCK_51
Vercel¶
CODE_BLOCK_52
Docker Deployment¶
CODE_BLOCK_53
CODE_BLOCK_54
Custom Domain¶
CODE_BLOCK_55
CODE_BLOCK_56
Custom Themes¶
Theme Structure¶
CODE_BLOCK_57
Base Template¶
CODE_BLOCK_58
Content Template¶
CODE_BLOCK_59
Navigation Template¶
CODE_BLOCK_60
Advanced Configuration¶
Multi-site Configuration¶
CODE_BLOCK_61
Environment Variables¶
CODE_BLOCK_62
Conditional Configuration¶
CODE_BLOCK_63
Custom Hooks¶
CODE_BLOCK_64
CODE_BLOCK_65
Internationalization¶
Multi-language Setup¶
CODE_BLOCK_66
Language-specific Content¶
CODE_BLOCK_67
Translation Structure¶
CODE_BLOCK_68
Search¶
Local Search Configuration¶
CODE_BLOCK_69
External Search Integration¶
CODE_BLOCK_70
CODE_BLOCK_71
Custom Search¶
CODE_BLOCK_72
API Documentation¶
Auto-generated API Docs¶
CODE_BLOCK_73
CODE_BLOCK_74
CODE_BLOCK_75
OpenAPI Integration¶
CODE_BLOCK_76
CODE_BLOCK_77
CODE_BLOCK_78
Manual API Documentation¶
CODE_BLOCK_79__http GET /api/v1/users Authorization: Bearer YOUR_API_KEY __CODE_BLOCK_80__json { "users": [ { "id": 1, "name": "John Doe", "email": "john@example.com" } ], "total": 100, "limit": 10, "offset": 0 } __CODE_BLOCK_81__bash curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://api.example.com/v1/users?limit=5" __CODE_BLOCK_82
Performance¶
Build Optimization¶
CODE_BLOCK_83
Caching Strategy¶
CODE_BLOCK_84
Image Optimization¶
CODE_BLOCK_85
CODE_BLOCK_86
Lazy Loading¶
CODE_BLOCK_87
Best Practices¶
Content Organization¶
CODE_BLOCK_88
Writing Best Practices¶
- Use clear headings for better navigation
- Include code examples with proper syntax highlighting
- Add screenshots for visual guidance
- Write concise descriptions for better understanding
- Use consistent formatting across all pages
- Include cross-references between related topics
SEO Optimization¶
CODE_BLOCK_89
Maintenance Best Practices¶
- Regular updates to keep content current
- Link checking to prevent broken links
- Performance monitoring for build times
- User feedback integration for improvements
- Version control for documentation changes
- Automated testing for documentation builds
Summary¶
MkDocs is a powerful static site generator specifically designed for project documentation. Key features include:
- Markdown-based: Write documentation in simple Markdown
- Python-powered: Extensible with Python plugins
- Theme support: Beautiful themes including Material Design
- Live preview: Real-time preview during development
- Easy deployment: Simple deployment to various platforms
- Plugin ecosystem: Rich ecosystem of plugins for extended functionality
- Search integration: Built-in search with external search support
- Multi-language: Support for internationalization
By following best practices and leveraging MkDocs' capabilities, you can create professional, maintainable documentation that serves your users effectively and grows with your project.
_