Docsbook
Aperçu

Migration de Docusaurus à Docsbook, étape par étape

Docusaurus est génial jusqu'à ce que la prochaine migration majeure arrive et que vous passiez un sprint dessus au lieu de livrer le produit. Ce guide décrit le chemin de migration réaliste.

Nous créons Docsbook. Nous vous dirons également quand la migration ne vaut pas la peine.

Quand vous ne devriez pas migrer#

Ignorez cette migration si :

  • Votre site Docusaurus utilise des intégrations de composants React lourds (démos interactives, plugins personnalisés). Docsbook est axé sur le markdown.
  • Vous avez un ingénieur dédié aux docs dont le travail inclut en partie Docusaurus. La plateforme a de réelles forces entre leurs mains.
  • Vous avez besoin d'un thème React profondément personnalisé. Docsbook vous offre des tokens de couleur, des polices, des commutateurs de mise en page, une configuration d'en-tête/pied de page — pas de personnalisation complète du thème.

Si l'un de ces points s'applique, restez sur Docusaurus et lisez le reste de ce guide plus tard.

TL;DR#

  1. Supprimer la syntaxe spécifique à MDX pour le markdown standard
  2. Pousser vers un dépôt GitHub (vous en avez déjà un)
  3. Connecter Docsbook
  4. Câbler un domaine personnalisé
  5. Porter les redirections
  6. Abandonner le pipeline CI et la facture d'hébergement

Étape 1 : MDX vers markdown#

Docusaurus utilise MDX, qui est markdown + JSX. Docsbook utilise markdown standard avec des extensions.

Trois classes de MDX qui nécessitent un traitement :

Imports et composants React#

import Foo from '@site/src/components/Foo';
 
<Foo />

Solutions :

  • Pour les visuels statiques : remplacez par une image hébergée et un lien vers une démo en direct
  • Pour les éléments interactifs : liez à votre application
  • Pour les onglets/admonitions : utilisez les blocs natifs de Docsbook (voir ci-dessous)

Avertissements#

Docusaurus :

:::note Title
Content
:::

Docsbook (markdown au goût de GitHub) :

> [!NOTE]
> Content

Rechercher et remplacer :

find . -name "*.mdx" -exec rename 's/\.mdx$/\.md/' {} \;
find . -name "*.md" -exec sed -i.bak -E 's/:::note/> [!NOTE]/g; s/:::tip/> [!TIP]/g; s/:::warning/> [!WARNING]/g; s/:::caution/> [!CAUTION]/g; s/:::info/> [!NOTE]/g; s/^:::$//' {} \;

Onglets et groupes de code#

Docsbook prend en charge les onglets via une syntaxe standard :

<Tabs>
  <Tab title="npm">npm install foo</Tab>
  <Tab title="pnpm">pnpm add foo</Tab>
</Tabs>

La plupart des onglets Docusaurus se traduisent un à un.

Étape 2 : Barre latérale et navigation#

Docusaurus utilise sidebars.js pour définir la navigation. Docsbook construit la navigation à partir de votre structure de dossiers et des métadonnées.

Si vous souhaitez un ordre spécifique :

---
title: "Quick Start"
order: 1
---

Si vous ne spécifiez pas d'ordre, Docsbook trie par ordre alphabétique. Déplacez les fichiers dans des dossiers ordonnés si vous avez besoin d'un regroupement explicite.

Vous pouvez supprimer sidebars.js, docusaurus.config.js, babel.config.js et le répertoire src/ après la migration.

Étape 3 : Connecter Docsbook#

Vos documents sont déjà dans docs/. Connectez le dépôt :

  • docsbook.io → Connectez-vous avec GitHub
  • Collez github.com/yourorg/yourrepo
  • Site en direct à docsbook.io/yourorg/yourrepo

Étape 4 : Domaine personnalisé#

Docsbook sert docs.yourcompany.com avec SSL automatique.

  • Tableau de bord Docsbook → Paramètres → Domaine
  • Entrez docs.yourcompany.com
  • Mettre à jour DNS : CNAME docs → cname.vercel-dns.com
  • Attendez 5 minutes pour SSL

Étape 5 : préservation des URL#

Les URL de Docusaurus ressemblent généralement à :

docs.yourcompany.com/docs/intro
docs.yourcompany.com/docs/category/guides/getting-started

Les URL de Docsbook correspondent à vos chemins de fichiers :

docs.yourcompany.com/intro.md → docs.yourcompany.com/intro
docs.yourcompany.com/guides/getting-started.md → docs.yourcompany.com/guides/getting-started

Si votre Docusaurus avait un préfixe /docs/ et que vous souhaitez maintenir la parité :

Option A : renommez le dossier local docs/ pour conserver le préfixe dans les URL (Docsbook servira à partir d'un chemin différent).

Option B : ajoutez des redirections des anciennes URL /docs/* vers les nouvelles URL /* à votre couche CDN ou DNS.

Étape 6 : Déposer le CI/CD#

Une fois que Docsbook reçoit du trafic :

# Files you can delete
rm -rf .docusaurus/
rm -rf build/
rm -rf node_modules/
rm docusaurus.config.js
rm sidebars.js
rm babel.config.js
rm -rf src/
rm -rf static/
# Keep docs/ — it is your source

Fichier de workflow GitHub Actions pour le déploiement de Docusaurus : à supprimer également.

Le résultat : déploiement des docs à chaque git push vers main, aucune minute CI utilisée.

Ce que vous gagnez#

Docusaurus Docsbook
Temps de construction 30–120 secondes par push 5 secondes de configuration totale
Coût d'hébergement Vercel/Netlify niveau pro Inclus
Chat AI Travail de plugin Intégré
Traductions Configuration par locale + pipeline de traduction Intégré, 15 langues
Migrations de version majeure Tous les 18 mois Jamais
Maintenance de thème Dérive de Swizzle Jetons de couleur, pas de maintenance

Ce que vous abandonnez#

  • Intégrations de composants React dans la documentation (hébergez-les ailleurs, liez-les)
  • Contrôle total du thème swizzle (vous obtenez des jetons de couleur/typo/mise en page)
  • Écosystème de plugins (la plupart des cas sont déjà intégrés)

Cas limites#

Algolia DocSearch#

Vous pouvez continuer à utiliser Algolia DocSearch sur Docsbook (pointez-le vers votre nouveau domaine). Ou utilisez la recherche intégrée de Docsbook, qui est incluse gratuitement.

Page d'atterrissage personnalisée#

Docusaurus a souvent une page d'atterrissage personnalisée à / construite en React. Docsbook sert votre README.md à /. Si vous souhaitez une page d'atterrissage de style marketing, hébergez-la séparément et pointez Docsbook vers docs.yourcompany.com au lieu de yourcompany.com.

Versionnage#

Le modèle docs/versioned_docs/version-1.0/ de Docusaurus n'est pas directement pris en charge. Options :

  • Utiliser des espaces de travail Docsbook séparés par version (docsbook.io/yourorg/yourrepo-v1)
  • Utiliser des branches Git et changer la branche indexée
  • Abandonner les anciennes versions (la plupart des équipes constatent qu'elles les maintenaient par habitude)

Temps#

  • Projet OSS, ~80 pages, MDX minimal : 2 heures
  • Startup, ~300 pages, MDX modéré : une demi-journée
  • Phase intermédiaire, ~1000 pages, MDX lourd : 1–2 jours

Testez la migration avant de vous y engager. Publier un deuxième site à partir du même dépôt ne coûte rien et ne change rien au déploiement de Docusaurus qui continue de servir vos lecteurs — si le résultat n'atteint pas la parité, vous avez perdu les cinq secondes que cela a pris.

Commencez gratuitement — pas de carte de crédit

Prochaines étapes#

Updated

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

Propulsé par Docsbook