# 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.

   ```bash
   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`.

   ```json
   {
     "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.

   ```mdx
   ---
   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` :

   ```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.

> **Note**
>
> `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](/docs/demarrer/mettre-en-ligne/).
- [Écrire une page](/docs/guides/ecrire-une-page/) : titres, liens, images, code.
- [Référence de docs.json](/docs/reference/docs-json/) pour tous les champs.