wiki/Catalogue-Self-Hosted/apps/app-mkdocs.md

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