Transformez votre README.md en un véritable site de documentation

La documentation de votre projet se trouve dans README.md. Vous avez toujours voulu mettre en place un véritable site de documentation. Vous avez regardé Docusaurus, ouvert le guide de configuration, puis fermé l'onglet.

Ce post est l'alternative de 5 secondes.

TL;DR#

• La plupart des projets OSS publient des docs uniquement en README.md
• Un README est acceptable, mais il n'est pas indexé sur Google aussi bien qu'un vrai site de docs, n'a pas de chat AI, pas d'analytique, pas de traductions
• Docsbook transforme un README.md (et un docs/ optionnel) en un site à docsbook.io/yourorg/yourrepo en 5 secondes
• Publier un dépôt public ne coûte rien. Pas de CI/CD, pas de fichiers de configuration.

Pourquoi un README ne suffit pas#

Trois pertes pour les projets uniquement avec README :

1. SEO#

Un README GitHub est indexé, mais Google classe github.com/user/repo pour le nom du dépôt, pas pour des requêtes techniques. Un utilisateur recherchant "comment s'authentifier avec la bibliothèque X" atterrit rarement sur le README, même lorsque la réponse s'y trouve.

Un vrai site de documentation à docs.yourproject.com (ou docsbook.io/yourorg/yourrepo) se classe pour les requêtes de longue traîne que votre README couvre mais ne peut pas faire remonter.

2. Distribution de l'IA#

ChatGPT et Perplexity citent des README GitHub, mais de manière incohérente. Un site de documentation propre avec llms.txt, des titres structurés et JSON-LD est cité beaucoup plus souvent.

Si votre projet dépend de la découverte par les développeurs, les citations d'IA sont désormais un véritable canal — voir Comment faire citer des docs par ChatGPT.

3. UX#

Un README de 1 500 lignes est un mur de défilement unique. Un site de documentation vous offre une barre latérale, une recherche, des titres en tant que liens d'ancrage, des fils d'Ariane, des boutons de copie de code. Même contenu, bien meilleure découvrabilité.

La configuration en 5 secondes#

Trois étapes :

1. Allez sur docsbook.io
2. Connectez-vous avec GitHub
3. Collez github.com/yourorg/yourrepo

Site en ligne à docsbook.io/yourorg/yourrepo. Votre README apparaît comme la page d'accueil. Si vous avez un dossier docs/, ces pages deviennent la barre latérale.

Aucune configuration. Pas de docsbook.config.js. Pas de pipeline CI/CD. Pas de déploiement.

Ce qui est indexé#

Docsbook lit :

• README.md à la racine du dépôt → page d'accueil
• docs/ dossier (récursivement) → pages du site
• docs/README.md → page d'atterrissage des docs
• Métadonnées YAML (title, description) → métadonnées de la page

Si vous n'avez qu'un README, vous obtenez un site de docs d'une page. Si vous avez docs/getting-started.md, docs/api.md, etc., vous obtenez un site multi-pages avec une barre latérale construite à partir de la structure des dossiers.

Frontmatter (facultatif)#

Ajoutez YAML en haut de tout fichier markdown :

---
title: "Quick Start"
description: "Get up and running in 60 seconds"
---
 
# Quick Start
...

title devient le titre de la page dans les moteurs de recherche. description devient la méta description. Si vous omettez les deux, Docsbook utilise le premier H1 comme titre et le premier paragraphe comme description.

Quel est le coût de la publication d'un projet OSS ?#

La publication du site ne coûte rien, et il en va de même pour quiconque le lit. Ce qui est mesuré, c'est l'utilisation de l'IA : chaque projet a son propre solde, et les questions à l'assistant et les exécutions de traduction l'utilisent. Les chiffres actuels se trouvent sur docsbook.io/pricing, générés à partir des constantes de tarification en direct à chaque demande.

La publication d'un dépôt vous donne :

• Tout dépôt public GitHub, rendu sous forme de site
• Nom de site personnalisé, icône, logo, couleurs d'accent pour le clair et le sombre
• Commutateur de thème, recherche, fil d'Ariane, boutons de copie de code
• Liens d'en-tête et liens sociaux (GitHub, Discord, X)
• Analytique — vues de page, pages principales, référents, pays
• llms.txt et llms-full.txt pour la découvrabilité de l'IA
• Un serveur MCP, afin que Claude Code et Cursor puissent lire et éditer la documentation
• Chat IA soutenu par votre README.md et docs/
• docs.yourproject.com avec SSL automatique

La seule chose que vous ne pouvez pas désactiver est le petit lien "Propulsé par Docsbook" dans le pied de page. Il s'affiche sur chaque site Docsbook, sans condition — c'est le prix à payer pour ne pas gérer l'hébergement vous-même.

Comment puis-je utiliser mon propre domaine au lieu de docsbook.io ?#

Pointez un sous-domaine vers Docsbook et il sert vos documents avec SSL provisionné automatiquement.

• Tableau de bord → Paramètres → Domaine
• DNS : CNAME docs → cname.vercel-dns.com
• SSL est automatique

Guide complet, y compris les domaines apex et les redirections : Domaine personnalisé pour la documentation.

Que se passe-t-il lorsque vous poussez#

Vous poussez un commit vers main. Docsbook indexe le changement et met à jour le site. Pas d'action GitHub, pas d'étape de construction. Le nouveau contenu est en ligne en quelques secondes.

Questions fréquentes#

Est-ce que cela fonctionne pour les dépôts privés ?#

Oui. Docsbook s'authentifie via votre portée OAuth GitHub, et le site publié peut être public ou privé.

Que dire de MDX ou des démos interactives ?#

Docsbook est d'abord axé sur Markdown. Pour les démos interactives, hébergez la démo ailleurs et liez-y. Si votre projet nécessite des composants React intégrés dans les pages de documentation, consultez Devriez-vous quitter Docusaurus en 2026 ? — Docusaurus est mieux adapté pour cela.

Ressemblera-t-il à tous les autres sites Docsbook ?#

Vous contrôlez les couleurs de la marque, les polices, la mise en page, l'en-tête, le pied de page, la barre latérale et votre propre domaine. La seule chose que vous ne pouvez pas supprimer est le petit lien "Propulsé par Docsbook" dans le pied de page — il apparaît sur chaque site Docsbook.

Puis-je déménager plus tard?#

Oui. Vos fichiers sont sur GitHub. Annulez l'abonnement, redirigez le DNS ailleurs, votre contenu reste intact.

Collez github.com/yourorg/yourrepo et le site est en ligne en cinq secondes. Rien n'est copié de votre dépôt, donc le README reste la source de vérité.

Commencez gratuitement — pas de carte de crédit

Étapes suivantes#

• Pourquoi les projets avec uniquement un README ont besoin d'un site de documentation — le cas pour faire cela
• Comment héberger la documentation à partir d'un dépôt GitHub — les deux autres options, avec des compromis
• Comparaison de l'hébergement gratuit de documentation — six options les unes contre les autres
• Domaine personnalisé pour la documentation — déplacer le résultat vers votre propre domaine