MkDocs Documentation Site Development
MkDocs is a Python-based documentation generator from Markdown. Popular in Python projects and DevOps teams. Material for MkDocs is the most feature-complete theme with search, versioning, and multilingual support.
Installation
pip install mkdocs mkdocs-material
mkdocs new my-docs
cd my-docs
mkdocs serve
mkdocs.yml
site_name: My Project
site_url: https://docs.myproject.com
repo_url: https://github.com/my-org/my-project
repo_name: my-org/my-project
theme:
name: material
language: ru
palette:
- scheme: default
primary: blue
accent: blue
toggle:
icon: material/brightness-7
name: Dark theme
- scheme: slate
primary: blue
accent: blue
toggle:
icon: material/brightness-4
name: Light theme
features:
- navigation.tabs
- navigation.tabs.sticky
- navigation.sections
- navigation.expand
- navigation.indexes
- navigation.top
- search.highlight
- search.suggest
- content.code.copy
- content.code.annotate
- content.tabs.link
- toc.integrate
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- attr_list
- md_in_html
- tables
- footnotes
- def_list
plugins:
- search:
lang: ru
- tags
- git-revision-date-localized:
type: date
locale: ru
- minify:
minify_html: true
nav:
- Home: index.md
- Guide:
- Installation: guide/installation.md
- Configuration: guide/configuration.md
- Quick Start: guide/quickstart.md
- API:
- Overview: api/overview.md
- Endpoints: api/endpoints.md
- Changelog: changelog.md
Advanced Markdown Components
# Features
!!! tip "Tip"
Use environment variables to store secrets.
!!! warning "Warning"
This method is deprecated in version 2.0.
=== "Python"
```python
import myproject
client = myproject.Client(api_key="...")
```
=== "JavaScript"
```javascript
const client = new MyProject({ apiKey: '...' });
```
```mermaid
sequenceDiagram
Client->>API: POST /auth/login
API->>Database: Check credentials
Database-->>API: User found
API-->>Client: JWT token
### Deploying to GitHub Pages
```yaml
# .github/workflows/docs.yml
name: Deploy Docs
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: actions/setup-python@v5
with: { python-version: '3.x' }
- run: pip install mkdocs-material mkdocs-git-revision-date-localized
- run: mkdocs gh-deploy --force
Basic MkDocs site with Material theme and 20–50 pages — 2–4 days.