Générateurs Sites Statiques & Docs

Ce que contient ce pack

Ce pack rassemble les cinq frameworks de sites statiques qui ont survécu au churn des frameworks JS et embarquent assez de features pour être un choix par défaut en 2026. La liste est tranchée : rien ici n'est un projet hobby « on génère du HTML depuis un Markdown unique » — chaque entrée a un vrai écosystème de plugins, une histoire de recherche, et un setup de production déployable.

L'ensemble couvre quatre formes : documentation développeur (VitePress, Docusaurus), pages marketing soignées (Astro), docs-as-a-service hébergé (Mintlify) et présentations que les ingénieurs veulent vraiment donner (Slidev). Un pack, quatre formats de sortie — choisissez celui qui correspond à votre audience.

Pourquoi ce stack

Les sites statiques sont de retour parce que les alternatives se sont avérées chères. Next.js server-rendered pour des pages marketing coûte plus en compute et complexité que générer du HTML au build. Ces cinq générateurs font la même chose : prendre du Markdown (ou MDX) plus un peu de config, et sortir du HTML statique que vous pouvez héberger sur n'importe quel CDN.

Où ils diffèrent :

• VitePress livre un thème « docs » qui rend bien out-of-the-box. Utilisé par Vue, Vite, Vitest eux-mêmes — fort signal dogfood.
• Astro est le plus large. Il peut construire un site de docs, mais aussi une landing page, un blog, un petit site marketing. L'architecture « Islands » signifie zéro JS sauf si un composant l'opt-in.
• Mintlify est la seule entrée hébergée. Vous écrivez du Markdown, poussez sur GitHub, et Mintlify héberge les docs rendus sur <vous>.mintlify.app (ou votre domaine). C'est un remplaçant SaaS pour Docusaurus auto-hébergé.
• Docusaurus est le plus lourd mais a le plus de plugins — docs versionnés, i18n, recherche, blog, tout de première classe. Choisissez-le quand vous avez besoin de versioning entre releases majeures.
• Slidev est le joker. Decks de slides Markdown-driven avec coloration syntaxique, composants interactifs et notes de présentateur. Les ingénieurs qui détestent Keynote l'adorent.

Installer en une commande

# Installe le pack — pose un template starter pour chaque builder dans votre projet
tokrepo install pack/static-site-docs

# Ou en choisir un
tokrepo install vitepress
tokrepo install astro
tokrepo install docusaurus

Le TokRepo CLI scaffold chaque framework dans sites/<framework>/ pour que vous compariez les sorties et choisissiez un gagnant avant de vous engager. Les cinq incluent un fichier .tokrepo/ avec les targets de déploiement production que nous avons validés (Vercel, Cloudflare Pages, Netlify, GitHub Pages).

Pièges courants

• VitePress est verrouillé sur Vue. Les composants custom doivent être en Vue. Si votre équipe est React-only, VitePress sera hostile — Docusaurus ou Mintlify sont les options React.
• L'hydratation MDX d'Astro est opt-in. Un <Counter client:load /> envoie du JS ; un <Counter /> simple non. Oublier client:* est le bug #1 « pourquoi mon bouton ne marche pas ».
• Mintlify signifie lock-in SaaS. Votre contenu est à vous (tout est en Markdown dans votre repo) mais le rendering, search et analytics vivent dans Mintlify cloud. Planifiez une voie d'export avant de vous engager.
• Les docs versionnés Docusaurus sont à sens unique. Une fois que vous coupez la version 2.0 des docs, les éditer rétroactivement est inconfortable. Soyez délibéré sur quand versionner.
• Les decks Slidev ne sont pas slides.dev.com. Ce sont votre repo. L'hébergement est à vous (Vercel marche bien). N'essayez pas de partager une URL localhost avec votre CEO cinq minutes avant un board.

Idées reçues

« Statique signifie mort » est un mythe. Les cinq frameworks supportent l'hydratation, les server functions ou le rendering hybride pour les parties qui en ont besoin. Astro peut opter pour SSR par route ; Docusaurus a du React client-side pour l'interactivité ; VitePress fait tourner Vue dans le browser pour toute page qui en a besoin. Le défaut est « envoie du HTML » ; l'échappatoire est « envoie du JS là où il gagne son poids. »

« Tous les générateurs statiques se valent » est aussi faux. Le choix entre VitePress et Docusaurus détermine qui peut contribuer à vos docs (gens Vue vs React). Le choix entre Astro et Mintlify détermine qui possède le pipeline de déploiement (vous vs Mintlify). Choisissez délibérément.