Publier la doc en site web — MkDocs / Docusaurus¶

Présentation / aide à la décision. On garde la documentation en Markdown dans docs/ (docs-as-code, versionnée avec le code). Un générateur de site lit ce dossier et le publie en site web navigable — sans rien réécrire, sans dupliquer, sans quitter le repo.

✅ Décision : on part sur Material for MkDocs. La config est en place à la racine du repo (mkdocs.yml + requirements-docs.txt). Le Guide A ci-dessous (§7) décrit exactement quoi faire sur Cloudflare Pages. Le comparatif et l'option Docusaurus sont conservés pour mémoire.

1. Le principe¶

docs/*.md  ──►  générateur (MkDocs ou Docusaurus)  ──►  site statique  ──►  hébergement
(la source                                              (HTML/CSS/JS)       (GitHub Pages
 versionnée)                                                                 ou Cloudflare Pages)

La source de vérité reste le Markdown dans docs/. Le site n'est qu'une vue générée à la demande (en local ou en CI). Rien à maintenir en double.

2. Ce que ça apporte (vs lire les `.md` sur GitHub)¶

Recherche plein-texte instantanée sur toute la doc.
Navigation / sommaire latéral auto, fil d'Ariane, page d'accueil soignée.
Rendu pro : thème cohérent, coloration syntaxique, admonitions (notes, avertissements), diagrammes Mermaid, mode clair/sombre.
URL propre et partageable (ex. docs.serpe.abel.fr) — pratique pour présenter au client.
Versioning de la doc (Docusaurus surtout) : garder la doc de chaque version du produit.
Publication automatique à chaque push (via une GitHub Action).

3. Les deux options¶

Option A — Material for MkDocs (recommandé ici)¶

Générateur Python, spécialisé documentation technique en Markdown pur.

Léger : une dépendance (mkdocs-material), un fichier mkdocs.yml.
Se branche directement sur notre docs/ existant (Markdown standard).
Fonctionnalités clés : recherche, navigation, thème Material, dark mode, admonitions, onglets de code, Mermaid, versioning (via mike).
Preview locale : mkdocs serve ; publication : mkdocs gh-deploy (ou Action).

Config minimale (mkdocs.yml à la racine — exemple, non installé) :

site_name: Documentation Serpe
docs_dir: docs
theme:
  name: material
  language: fr
  features: [navigation.sections, navigation.top, search.suggest, content.code.copy]
  palette:
    - scheme: default   # clair
      toggle: { icon: material/weather-night, name: Mode sombre }
    - scheme: slate     # sombre
      toggle: { icon: material/weather-sunny, name: Mode clair }
markdown_extensions: [admonition, pymdownx.superfences, pymdownx.tabbed]
# nav: optionnel — sinon l'arborescence de docs/ sert de menu

Option B — Docusaurus¶

Générateur React / Node, orienté portail produit (doc + blog + i18n).

Plus riche : versioning natif, blog, internationalisation, MDX (composants React dans le Markdown), écosystème de plugins, recherche Algolia.
Plus lourd : projet Node à part (npx create-docusaurus), build React, quelques ajustements Markdown (front-matter, MDX).
Pertinent si on veut à terme un vrai site produit (pas seulement de la doc interne) : pages marketing, versions multiples, composants interactifs.

4. Comparatif¶

Critère	Material for MkDocs	Docusaurus
Écosystème	Python	React / Node
Mise en place	Très simple (1 fichier)	Projet Node dédié
Colle à notre `docs/` Markdown	Oui, direct	Oui, avec ajustements
Recherche	Intégrée	Intégrée / Algolia
Dark mode, nav, Mermaid	✅	✅
Versioning de doc	via `mike`	Natif
Blog / i18n / composants React	Limité	Oui (MDX)
Idéal pour	Doc technique interne	Portail produit complet

5. Comment on le brancherait (le jour venu)¶

Ajouter le générateur en dev-dépendance + un fichier de config qui pointe sur docs/ (aucune migration de contenu).
Une GitHub Action build + publie le site à chaque push sur main (GitHub Pages, ou Cloudflare Pages — cohérent avec l'app).
Optionnel : un sous-domaine (docs.serpe.abel.fr).

Le workflow d'écriture ne change pas : on continue d'éditer les .md dans docs/, relus en PR. Le site se régénère tout seul.

6. Recommandation¶

Pour ce projet — documentation technique en Markdown, POC, équipe réduite — Material for MkDocs est le meilleur rapport simplicité/valeur : il se branche en quelques minutes sur le docs/ déjà en place, sans rien réécrire, et donne recherche + navigation + rendu soigné.

Docusaurus deviendra intéressant plus tard si le besoin évolue vers un portail produit (doc versionnée par release, composants interactifs, blog, multilingue).

À ce stade : rien à installer. Ce document présente l'option ; on branche le générateur quand tu le décides. La doc reste, quoi qu'il arrive, en Markdown versionné dans docs/.

7. Déploiement — les 2 guides¶

Réponses courtes : - Comment ça se déploie ? Les deux génèrent un site statique (HTML/CSS/JS) à partir du Markdown : MkDocs → dossier site/, Docusaurus → dossier build/. On héberge ce dossier statique. - Sur Cloudflare Pages ? Oui, parfaitement (Cloudflare Pages sert des sites statiques). C'est cohérent avec l'app (déjà sur Cloudflare). - Un repo à part ? Non. On reste dans ce repo (la doc reste dans docs/). On crée juste un second projet Cloudflare Pages qui construit le site de doc — l'app et la doc = 2 projets Pages, 1 seul repo.

Guide A — Material for MkDocs sur Cloudflare Pages (mis en place)¶

Les deux fichiers sont déjà à la racine du repo (branche docs/site-documentation) : - mkdocs.yml → thème Material, langue FR, nav complète, recherche. - requirements-docs.txt → mkdocs-material>=9.5,<10 (nom distinct de requirements.txt pour ne pas se confondre avec l'app Node).

Côté Cloudflare Pages (une seule fois) : 1. Workers & Pages → Create application → Pages → Connect to Git → ce repo. 2. Nom du projet : serpe-doc (distinct de l'app serpe-ao-poc). 3. Branche de production : main (la doc n'est en ligne qu'après merge dans main ; chaque PR génère en plus un déploiement de preview). 4. Build settings : - Framework preset : None - Build command : pip install -r requirements-docs.txt && mkdocs build - Build output directory : site - Root directory : / (racine du repo) 5. Variables d'environnement → ajouter PYTHON_VERSION = 3.12 (force une version de Python récente sur l'image de build Cloudflare). 6. Save and Deploy. Ensuite, chaque push sur main republie automatiquement. 7. Custom domains → doc.serpe.abel.fr (déjà configuré, renseigné comme site_url dans mkdocs.yml) ; l'URL par défaut reste https://serpe-doc.pages.dev.

Alternative sans Cloudflare : pip install -r requirements-docs.txt && mkdocs gh-deploy publie sur GitHub Pages (branche gh-pages) en une commande.

Alternative sans Cloudflare : mkdocs gh-deploy publie sur GitHub Pages (branche gh-pages) en une commande.

Guide B — Docusaurus sur Cloudflare Pages¶

Docusaurus est un projet Node à part, rangé dans un sous-dossier du repo (ex. website/), qui consomme le contenu Markdown. 1. Dans le repo : npx create-docusaurus@latest website classic, puis configurer website/docusaurus.config.js pour pointer le plugin docs sur ../docs (ou déplacer les .md dans website/docs/). 2. Cloudflare → Create Pages project (même repo), nom serpe-docs. 3. Build settings : - Root directory : website - Build command : npm ci && npm run build - Build output directory : build (relatif à website/ → website/build) - Node : fichier .node-version (déjà 24.11.0 dans le repo). 4. Domaine : Custom domains → docs.serpe.abel.fr.

Récap¶

	MkDocs	Docusaurus
Où vit le générateur	racine (`mkdocs.yml`)	sous-dossier `website/`
Build command	`pip install -r requirements-docs.txt && mkdocs build`	`npm ci && npm run build`
Output	`site`	`build` (root `website`)
Repo séparé ?	Non	Non
Projet Cloudflare Pages	`serpe-doc` (2e projet, même repo)	`serpe-docs` (2e projet, même repo)