Initial vault setup
This commit is contained in:
@@ -0,0 +1,151 @@
|
||||
---
|
||||
title: MkDocs
|
||||
created: 2026-06-07
|
||||
updated: 2026-06-07
|
||||
type: app
|
||||
tags: [catalogue, wiki, documentation, static-site, markdown, python, mkdocs-material, docker]
|
||||
confidence: high
|
||||
contested: false
|
||||
sources: [https://selfh.st/apps/?tag=wiki]
|
||||
---
|
||||
|
||||
# 📖 MkDocs
|
||||
|
||||
> Générateur de site statique pour documentation technique, écrit en Python. Rapide, simple, minimaliste. Avec le thème **Material for MkDocs**, c'est l'une des stacks de doc les plus populaires du monde open source.
|
||||
|
||||
| Métadonnée | Valeur |
|
||||
| :--- | :--- |
|
||||
| **Site web** | [mkdocs.org](https://www.mkdocs.org/) |
|
||||
| **GitHub** | [mkdocs/mkdocs](https://github.com/mkdocs/mkdocs) |
|
||||
| **License** | BSD-2-Clause |
|
||||
| **Langage** | Python |
|
||||
| **Étoiles** | ⭐ 2631 |
|
||||
| **Dernière MAJ** | 2026-05-26 |
|
||||
| **Catégorie** | [[cat-wiki]] |
|
||||
|
||||
## Description
|
||||
|
||||
MkDocs est un **générateur de site statique spécialisé documentation**, écrit en Python, qui transforme un dossier de fichiers Markdown en un site web statique propre et navigable. Sa philosophie : **« project documentation with Markdown »**. L'outil est volontairement minimaliste, sans JS lourd, sans base de données, sans serveur applicatif : on écrit du Markdown, on configure un `mkdocs.yml`, on lance `mkdocs build`, et on sert le dossier `site/` avec n'importe quel serveur HTTP.
|
||||
|
||||
L'écosystème est dominé par le thème **Material for MkDocs** (de Piotr Adamczyk, dit « squidfunk ») qui apporte : recherche instantanée, code highlighting, Mermaid/JSDiagrams, admonitions, tabs, snippets, support multilingue, dark mode toggle, génération PDF/Print, et des centaines d'options. C'est devenu le standard de facto pour la documentation de projets Python, Kubernetes, FastAPI, et bien d'autres.
|
||||
|
||||
MkDocs est purement statique : on l'utilise pour **publier** de la doc, pas pour gérer un wiki en ligne. Pour de l'édition collaborative interne, on s'orientera vers [[app-wiki-js]] ou [[app-docmost]]. Pour du Node/MDX/React, le concurrent direct est [[app-docusaurus]].
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1 : Docker
|
||||
|
||||
L'image `squidfunk/mkdocs-material` permet de servir ou builder le site sans installer Python localement.
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
mkdocs-serve:
|
||||
image: squidfunk/mkdocs-material:latest
|
||||
container_name: mkdocs
|
||||
restart: unless-stopped
|
||||
command: serve --dev-addr 0.0.0.0:8000
|
||||
volumes:
|
||||
- ./docs:/docs
|
||||
- ./mkdocs.yml:/mkdocs.yml:ro
|
||||
ports:
|
||||
- "8000:8000"
|
||||
|
||||
mkdocs-build:
|
||||
image: squidfunk/mkdocs-material:latest
|
||||
container_name: mkdocs-build
|
||||
profiles: ["build"]
|
||||
volumes:
|
||||
- ./docs:/docs
|
||||
- ./mkdocs.yml:/mkdocs.yml:ro
|
||||
- ./site:/site
|
||||
command: build --strict
|
||||
```
|
||||
|
||||
Pour un **build CI/CD** on utilise le profil `build`, et on uploade `./site/` sur le serveur cible (S3, Pages, etc.).
|
||||
|
||||
### Option 2 : Installation manuelle (Python)
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install mkdocs mkdocs-material mkdocs-minify-plugin
|
||||
# ou : pip install mkdocs-material[recommended]
|
||||
```
|
||||
|
||||
Prérequis : **Python 3.8+**. Le `mkdocs.yml` à la racine du projet décrit la nav, le thème, les plugins et la configuration.
|
||||
|
||||
```bash
|
||||
mkdocs new mon-projet # crée docs/index.md et mkdocs.yml
|
||||
cd mon-projet
|
||||
mkdocs serve # serveur dev avec HMR sur :8000
|
||||
mkdocs build # génère ./site/
|
||||
mkdocs gh-deploy # déploiement GitHub Pages en une commande
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Le fichier `mkdocs.yml` pilote tout :
|
||||
|
||||
- **site_name, site_url, site_description** : métadonnées globales.
|
||||
- **theme** : `theme: material` active le thème Material (et ses features via `features:`).
|
||||
- **nav** : structure du menu. Exemple :
|
||||
```yaml
|
||||
nav:
|
||||
- Accueil: index.md
|
||||
- Guide:
|
||||
- Démarrage: guide/start.md
|
||||
- Config: guide/config.md
|
||||
- API: api.md
|
||||
```
|
||||
- **plugins** : `search`, `minify`, `git-revision-date-localized`, `mkdocstrings` (auto-génération depuis docstrings Python).
|
||||
- **markdown_extensions** : `admonition`, `pymdownx.highlight`, `pymdownx.superfences`, `pymdownx.tabbed`, `pymdownx.tasklist`, etc.
|
||||
- **extra** : variables injectées dans le thème, `social`, `analytics`, `generator: false` pour cacher le footer MkDocs.
|
||||
- **palette** : dark/light toggle, primary/accent color.
|
||||
- **strict: true** en CI : fait échouer le build en cas de lien mort (très utile).
|
||||
|
||||
## Alternatives
|
||||
|
||||
### Open Source
|
||||
|
||||
- [[app-docusaurus]] — Équivalent Node/React/MDX, plus « marketing-friendly ».
|
||||
- [[app-wiki-js]] — Wiki éditable, pas publication.
|
||||
- [[app-docmost]] — Wiki collaboratif, pas statique.
|
||||
- [[app-raneto]] — Wiki Markdown Node, plus minimaliste.
|
||||
- **Sphinx** — Standard Python historique (utilisé par Python, Django, NumPy).
|
||||
- **Antora** — Multi-repo AsciiDoc, gros projets modulables.
|
||||
- **Hugo** — Statique généraliste Go, plus rapide mais moins orienté doc.
|
||||
- **Docusaurus (encore)** — Plus complet pour un site de projet avec blog, i18n poussé, versioning.
|
||||
|
||||
### Propriétaires (ce que MkDocs remplace)
|
||||
|
||||
- **ReadTheDocs** (hébergé) — MkDocs + Material est porté par la communauté RTD.
|
||||
- **Gitbook** (cloud) — MkDocs fait le même job en self-hosted, gratuitement.
|
||||
- **Notion (en export)** — Quand on veut un site public, MkDocs est plus propre.
|
||||
- **Confluence (en publication)** — Pour publier la doc en public, MkDocs est plus adapté.
|
||||
|
||||
## Sécurité
|
||||
|
||||
- ✅ **100 % statique** : pas de serveur applicatif, pas de BDD, surface d'attaque nulle.
|
||||
- ✅ Site auditable et généré depuis un dépôt Git, parfait pour les revues de code de la doc.
|
||||
- ⚠️ Bien configurer `strict: true` pour casser le build sur les liens cassés ou les pages manquantes.
|
||||
- ⚠️ Le **thème Material** reçoit des MAJ fréquentes (sécurité et features) : mettre à jour `mkdocs-material` régulièrement via Dependabot.
|
||||
- ✅ **HTTPS** au point de service (Caddy, Nginx, Cloudflare, etc.).
|
||||
- ✅ Si on active `mkdocstrings` avec des docstrings Python, attention à ne pas exposer de secrets dans la doc auto-générée.
|
||||
- ⚠️ Les **plugins tiers** ont accès à toute la doc : limiter aux plugins officiels squidfunk ou bien étoilés/maintenus.
|
||||
|
||||
## Ressources
|
||||
|
||||
- [Site officiel MkDocs](https://www.mkdocs.org/)
|
||||
- [Documentation](https://www.mkdocs.org/getting-started/)
|
||||
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
|
||||
- [GitHub mkdocs/mkdocs](https://github.com/mkdocs/mkdocs)
|
||||
- [Awesome MkDocs](https://github.com/mkdocs/awesome-mkdocs)
|
||||
|
||||
## Pages Liées
|
||||
|
||||
- [[cat-wiki]] — Vue d'ensemble de la catégorie Wiki
|
||||
- [[app-docusaurus]] — Concurrent Node/MDX
|
||||
- [[app-wiki-js]] — Wiki éditable
|
||||
- [[app-docmost]] — Wiki collaboratif moderne
|
||||
- [[recettes-docker-compose]] — Templates Docker partagés
|
||||
Reference in New Issue
Block a user