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
GitHub	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.

# 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)

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.

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 :

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

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

6.6 KiB Raw Permalink Blame History