Ta première doc en local

Ce tutoriel fait tourner un site de documentation sur ton poste. Pas de compte, pas de connexion : à la fin, ta doc s’ouvre sur http://localhost:4321/.

Avant de commencer : Node.js ou Bun, et un terminal.

1. Créer le dossier

   Le dossier peut être un dépôt à part, ou un dossier docs/ dans le dépôt de ton produit.

   mkdir docs && cd docs
   npm init -y
   npm install --save-dev @hgdc/docs

   Avec Bun, bun add --dev @hgdc/docs fait la même chose.

2. Écrire docs.json

   Crée docs.json à la racine du dossier. Deux champs sont obligatoires : name et navigation.

   {
     "name": "Documentation Acme",
     "colors": { "primary": "#0f766e" },
     "navigation": {
       "groups": [{ "group": "Démarrer", "pages": ["index", "installation"] }]
     }
   }

   Chaque chemin de pages correspond à un fichier, sans extension : installation désigne installation.mdx.

3. Écrire les pages

   Crée index.mdx et installation.mdx. Chaque page commence par un titre et une description.

   ---
   title: Installation
   description: Installer Acme en deux minutes.
   ---
   
   Lance la commande suivante dans ton terminal.

4. Lancer le site

   Ajoute les scripts dans package.json :

   {
     "scripts": {
       "dev": "hgdc-docs dev",
       "build": "hgdc-docs build"
     }
   }

   Puis lance npm run dev et ouvre http://localhost:4321/. Le site se recharge à chaque modification d’une page.

hgdc-docs build écrit le site dans dist/, et le cache de Docs dans .hgdc-docs/. Ajoute les deux dossiers à ton .gitignore.

Si ça ne marche pas

• docs.json n'est pas un JSON valide : une virgule en trop ou un guillemet manquant. Le message donne la position.
• docs.json cite des pages absentes du dossier : la liste donne les fichiers manquants. Crée-les, ou retire-les de navigation.
• Le port 4321 est déjà utilisé : lance npm run dev -- --port 4000.
• La barre latérale ne change pas après une modification de docs.json : arrête npm run dev et relance-le.

Et ensuite

• Mettre ta doc en ligne et activer l’assistant.
• Écrire une page : titres, liens, images, code.
• Référence de docs.json pour tous les champs.