Docsbook
Aperçu

Comment héberger la documentation à partir d'un dépôt GitHub

Vous avez des fichiers markdown dans un dépôt GitHub. Vous voulez qu'ils soient accessibles à une véritable URL — recherchable, de marque, indexée par Google, lisible sur mobile. Le dépôt est la source de vérité ; le site web est la surface.

Il existe trois chemins courants pour y parvenir. Ce tutoriel passe en revue chacun d'eux, avec les étapes de configuration réelles et les compromis.

Que possédez-vous déjà ?#

Un dépôt de documentation typique ressemble à ceci :

my-product/
├── README.md
├── docs/
│   ├── getting-started.md
│   ├── api-reference.md
│   └── guides/
│       └── webhooks.md

Vous voulez que cela devienne un site web. Les trois options réalistes sont :

  1. GitHub Pages — gratuit, brut, manuel
  2. Docusaurus — lourd en code, auto-hébergé, personnalisable jusqu'au composant de thème
  3. Docsbook — instantané, géré, collez-l'URL

Option 1 : GitHub Pages avec Jekyll#

GitHub Pages sert des sites statiques à partir d'une branche de dépôt gratuitement. Avec un _config.yml il prend Jekyll et rend votre markdown.

Étapes#

  1. Créer _config.yml à la racine du dépôt : 
    theme: jekyll-theme-minimal
title: My Product Docs
  2. Allez dans Paramètres → Pages dans votre dépôt
  3. Définir la source sur la branche main, le dossier /docs
  4. Attendez quelques minutes — votre site est en ligne à username.github.io/repo

Ce que vous obtenez#

  • Une URL fonctionnelle
  • Thème de base
  • Hébergement gratuit

Qu'est-ce qui manque#

  • Aucune recherche
  • Aucune barre de navigation sans configuration manuelle
  • Aucune analyse
  • Les thèmes Jekyll ressemblent à 2014
  • Le domaine personnalisé fonctionne mais vous devez configurer DNS et SSL vous-même
  • Aucune fonctionnalité AI, aucune traduction, aucun SEO prêt à l'emploi

Bon pour un wiki interne. Pas bon si vos documents sont une surface de produit destinée aux clients.

Option 2 : Docusaurus#

Docusaurus est le framework de documentation open-source de Meta. Il est basé sur React et personnalisable jusqu'aux composants individuels — si vous êtes prêt à le maintenir.

Étapes#

  1. Installez Node.js 18+ localement
  2. Générez le projet : 
    npx create-docusaurus@latest my-docs classic
cd my-docs
  3. Déplacez vos fichiers markdown existants dans le dossier docs/ créé par Docusaurus
  4. Modifiez docusaurus.config.js — définissez le titre du site, l'URL de base, la structure de la barre latérale, les couleurs du thème, les éléments de la barre de navigation
  5. Modifiez sidebars.js — déclarez quels fichiers apparaissent dans quel ordre
  6. Exécutez npm run start pour prévisualiser localement
  7. Construisez : npm run build
  8. Déployez sur Vercel, Netlify ou GitHub Pages — configurez le pipeline de déploiement, les variables d'environnement, les commandes de construction
  9. Configurez un domaine personnalisé — pointez le DNS, attendez la provision SSL
  10. Ajoutez des analyses — intégrez Plausible, GA ou votre outil de choix manuellement
  11. Ajoutez une recherche — payez pour Algolia DocSearch (ou auto-hébergez Meilisearch)
  12. Mettez à jour tout à chaque publication de produit

Ce que vous obtenez#

  • Contrôle total sur le design et la structure
  • Une base de code React que vous pouvez étendre
  • Une communauté open source pérenne

Ce qui manque#

  • Temps. La configuration réelle est un projet de 2 à 3 jours, puis une maintenance continue chaque fois qu'une dépendance est mise à jour
  • Recherche AI, chat AI, traduction AI — non inclus
  • Vous possédez chaque ligne de configuration

Bon si la documentation est elle-même un produit que votre équipe possède et expédie. Douloureux si ce que vous voulez, c'est que vos docs soient en ligne.

Option 3 : Docsbook#

Docsbook est une plateforme gérée qui transforme un dépôt GitHub en un site de documentation instantanément. Pas de CI/CD, pas de fichiers de configuration, pas de pipeline de construction.

Étapes#

  1. Allez sur docsbook.io
  2. Connectez-vous avec GitHub
  3. Collez l'URL de votre dépôt (par ex. github.com/your-org/your-repo)
  4. Fait — votre site est en ligne à docsbook.io/your-org/your-repo

C'est tout. Chaque git push met à jour le site automatiquement.

Ce que vous obtenez dès la sortie de la boîte#

  • Chatbot IA formé sur vos documents, afin que les utilisateurs obtiennent des réponses au lieu de résultats de recherche
  • Traduction IA en 15 langues, chacune indexée séparément par Google
  • Domaine personnalisé comme docs.yourcompany.com avec SSL gratuit
  • SEO — balises méta, plan du site, OpenGraph, JSON-LD, tout automatique
  • llms.txt généré pour les moteurs de recherche IA (ChatGPT, Perplexity, Claude)
  • Analytique — vues de page, pages principales, référents, questions posées à l'IA
  • Personnalisation de la marque — logo, couleurs, polices, thème — sans toucher au code
  • Serveur MCP afin que les agents IA puissent lire et gérer vos documents de manière programmatique

Ce qui manque#

  • Vous ne possédez pas le pipeline de rendu — mais votre markdown reste dans votre dépôt, donc il n'y a pas de verrouillage. Annulez à tout moment et vos documents vous accompagnent.

Quelle option devriez-vous choisir?#

Cas d'utilisation Choisir
Projet personnel, wiki interne GitHub Pages
Vous avez une équipe frontend et des opinions de design Docusaurus
Vous voulez des docs en direct cet après-midi et prêtes pour le SEO Docsbook

La réponse honnête : si la documentation n'est pas votre produit, ne construisez pas une plateforme de documentation. Utilisez-en une.

Essayez-le#

Héberger des documents depuis GitHub signifiait auparavant un dépôt de configuration, un pipeline de déploiement et un nettoyage récurrent. Collez l'URL de votre dépôt et le site est en ligne ; le Markdown ne quitte jamais le dépôt, donc le mouvement est réversible.

Commencez gratuitement — pas de carte de crédit

Étapes suivantes#

Updated

Cette page vous a-t-elle été utile ?

Propulsé par Docsbook