Aller au contenu principal

Gérer les erreurs Docusaurus

Voir aussi le glossaire Docusaurus pour les notions comme broken link, doc ID, TOC ou breadcrumb.

Session pratique pour diagnostiquer et corriger les erreurs les plus fréquentes sans assistance.

Objectif​

Être autonome quand une commande Docusaurus remonte une erreur :

  1. Identifier le bon type d'erreur
  2. Utiliser la bonne commande de diagnostic
  3. Corriger au bon endroit
  4. Revalider

Étape 1 — Commandes de support (liste complète)​

Depuis devs/web-site, les commandes disponibles sont :

npm start
npm run build
npm run serve
npm run clear
npm run deploy
npm run docusaurus -- --help

Étape 2 — Détail de chaque commande​

npm start​

Cette commande démarre le serveur de développement avec rechargement automatique et sert à prévisualiser les modifications en temps réel. Usage : lancer la commande puis ouvrir le site local indiqué dans le terminal. Contrainte : le terminal reste occupé tant que le serveur tourne, donc pour exécuter une autre commande il faut ouvrir un second terminal ou arrêter avec Ctrl + C. Erreurs typiques : Invalid sidebar file, document ids do not exist, Cannot read package.json (si lancé hors dossier projet). Remédiation : corriger les doc IDs dans sidebars.js, vérifier le dossier courant (devs/web-site), puis relancer.

npm run build​

Cette commande produit le build de production et c'est la référence pour valider la documentation avant commit. Usage : l'exécuter après un lot de changements pour détecter les erreurs globales. Contrainte : plus strict que npm start, il peut remonter des erreurs de liens que le mode dev ne bloque pas. Erreurs typiques : Docusaurus found broken links, routes invalides, incohérences de config. Remédiation : lire source page path et linking to dans la sortie, corriger les broken links dans les fichiers source, puis relancer jusqu'à build vert.

npm run serve​

Cette commande sert localement le dossier build pour tester le résultat final (production) dans un navigateur. Usage : lancer npm run build puis npm run serve. Contrainte : nécessite un build existant et à jour, sinon le rendu ne reflète pas les dernières modifs. Erreurs typiques : build absent, comportement différent entre dev et prod (liens, assets, navigation). Remédiation : refaire npm run build, puis relancer npm run serve et tester les pages critiques.

npm run clear​

Cette commande nettoie le cache Docusaurus (notamment .docusaurus) pour supprimer les artefacts locaux qui peuvent provoquer des comportements incohérents. Usage : à lancer quand une erreur persiste malgré une correction apparente. Contrainte : après nettoyage, le prochain build peut être plus long. Erreurs typiques : état local incohérent, contenu obsolète, metadata non rafraîchie. Remédiation : exécuter npm run clear, puis enchaîner avec npm run build.

npm run deploy​

Cette commande publie le site selon la configuration de déploiement Docusaurus (souvent GitHub Pages). Usage : uniquement quand le build local est propre. Contrainte : dépend de la configuration git/remote/permissions, ce n'est pas une commande de diagnostic local. Erreurs typiques : droits insuffisants, mauvaise branche cible, configuration de dépôt incorrecte. Remédiation : vérifier docusaurus.config.js (organizationName, projectName, url, baseUrl) et l'authentification git avant de relancer.

npm run docusaurus -- --help​

Cette commande affiche l'aide CLI Docusaurus et les options disponibles pour les sous-commandes. Usage : utile pour découvrir des flags avancés et comprendre les capacités de diagnostic. Contrainte : c'est une commande d'information, elle ne valide pas le site à elle seule. Erreurs typiques : aucune côté contenu docs, sauf problème d'environnement npm/node. Remédiation : vérifier la version de Node supportée et réinstaller les dépendances si nécessaire.

Exemple de séquence support recommandée :

npm run clear
npm run build
npm run serve

Retrouver un npm run actif avant de le stopper​

Si un terminal semble bloque ou si un ancien serveur tourne encore, commencez par identifier le process avant de le tuer.

1. Lister les process Node actifs​

Get-Process node | Select-Object Id, ProcessName, Path

2. Voir la ligne de commande exacte​

Get-CimInstance Win32_Process |
  Where-Object { $_.Name -in @('node.exe', 'npm.cmd', 'cmd.exe') } |
  Where-Object { $_.CommandLine -match 'docusaurus|npm run start|npm start|npm run serve' } |
  Select-Object ProcessId, Name, CommandLine

3. Vérifier quel process écoute sur le port attendu​

Exemple pour le port 3000 :

Get-NetTCPConnection -LocalPort 3000 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

Puis afficher le process associé :

Get-Process -Id <PID> | Select-Object Id, ProcessName, Path

4. Si besoin, arrêter proprement le process identifié​

Stop-Process -Id <PID>

Bon réflexe : ne tuez pas le process au hasard. Vérifiez d'abord le PID, le port et la CommandLine pour être sûr qu'il s'agit bien du run npm à diagnostiquer.

Étape 3 — Lire le message et classer l'erreur​

Type A — Invalid sidebar file / document ids do not exist​

Cause : doc ID incorrect dans sidebars.js.

Méthode :

  1. Repérer l'ID en erreur
  2. Vérifier le fichier réel sous docs/
  3. Corriger le doc ID dans sidebars.js

Règle de doc ID :

  • Chemin relatif à docs/
  • Sans extension .md
  • Les préfixes numériques (01_, 02_) sont retirés dans l'ID

Exemple :

  • Fichier : docs/docusaurus/05_gerer_erreurs.md
  • ID attendu : docusaurus/gerer_erreurs

Type B — Docusaurus found broken links​

Cause : lien Markdown ou lien de config vers une route inexistante.

Méthode :

  1. Lire source page path
  2. Ouvrir la page source
  3. Corriger la cible
  4. Relancer npm run build

Bonnes pratiques sur ce projet :

  • Préférer les liens docs absolus (/docs/...)
  • Pour une page d'index de dossier :
    • bon : /docs/docusaurus
    • mauvais : /docs/docusaurus/index
  • Pour VCF Automation :
    • bon : /docs/vcf-automation
    • mauvais : /docs/vcf-automation/README

Type C — Cannot read package.json (ENOENT)​

Cause : commande lancée dans le mauvais dossier.

Correction :

cd C:\dso-conseils\devs\web-site
npm run build

Étape 4 — Checklist de validation autonome​

  • Je suis dans devs/web-site
  • npm start fonctionne (si besoin de preview)
  • npm run build passe sans erreur
  • La navigation Docs fonctionne (header / navbar, footer, sidebar)
  • Les nouvelles pages sont visibles et accessibles

Si tout est vert, la documentation est prête.