Compilation et dossier dist/

Trois modes de fonctionnement

Commande	Ce qu’elle fait	Quand l’utiliser
npm run dev	Lance un serveur qui compile chaque page à la demande et la recharge dès qu’un fichier change. Rien n’est écrit sur disque.	Pendant la rédaction
npm run build	Compile tout le site d’un coup dans dist/.	Avant de publier
npm run preview	Sert le contenu de dist/ tel quel.	Pour vérifier le résultat final

Attention

Certaines fonctionnalités n’existent qu’après un build : la recherche, notamment, ne fonctionne pas en mode dev car son index est généré à la fin de la compilation.

Les étapes de npm run build

1. Chargement de la configuration Astro lit astro.config.mjs et initialise Starlight.

2. Synchronisation du contenu La collection docs est chargée : chaque fichier de src/content/docs/ est lu, son frontmatter est validé contre le schéma. Une erreur ici arrête tout.

3. Bundling (Vite) Le CSS et le peu de JavaScript nécessaire sont regroupés, minifiés, et nommés avec une empreinte (common.C0YgMi_o.css).

4. Génération des pages Pour chaque page, le Markdown est converti en HTML puis inséré dans le gabarit de Starlight. Le journal affiche une ligne par page :

   ├─ /guides/getting-started/index.html (+5ms)

5. Optimisation des images Les images de src/ sont compressées et converties.

6. Indexation pour la recherche Pagefind parcourt le HTML généré et construit un index de recherche découpé en petits fragments, téléchargés par le navigateur uniquement au besoin.

Le tout prend environ 2 secondes pour ce site.

Le contenu de dist/

• Répertoiredist/

  • index.html page d’accueil
  • 404.html page « introuvable »
  • favicon.svg copié depuis public/
  • Répertoire_astro/ CSS, JS et images, avec empreinte dans le nom

    • common.C0YgMi_o.css
    • houston.CZZyCf7p_Z1lAhR9.webp
    • …
  • Répertoireguides/

    • Répertoiregetting-started/

      • index.html
    • …
  • Répertoireconcepts/

    • …
  • Répertoirepagefind/ index de recherche et son script

    • pagefind.js
    • …

Points importants :

• Ce dossier est autonome. Il ne dépend plus ni de Node.js, ni d’Astro. N’importe quel serveur de fichiers peut le servir : Nginx, Apache, Caddy, GitHub Pages, GitLab Pages, un bucket S3, ou même python3 -m http.server.
• Il est entièrement régénéré à chaque build. Inutile (et vain) de le modifier à la main.
• Il n’est pas versionné dans Git : on versionne les sources, et on reconstruit.

Servir le site

Le projet propose trois façons de servir dist/ (voir aussi Démarrage) :

npm run preview       # serveur d'Astro                    → http://localhost:4321
npm run serve         # serveur Python, sans Astro          → http://localhost:8080
npm run serve:nginx   # Nginx dans Docker (proche production) → http://localhost:8081

Pour la production avec Decap CMS, deploy/docker-compose.yml ajoute le serveur de connexion OAuth (voir Decap CMS : architecture et mise en production).

La configuration Nginx fournie (deploy/nginx.conf) ajoute ce qu’un serveur minimal ne fait pas : renvoyer la page 404.html de Starlight, rediriger /page vers /page/, et demander aux navigateurs de garder en cache les fichiers de _astro/ (sans risque, puisque leur nom change à chaque modification).

Vers la publication automatique

Avec Decap CMS, le scénario est le suivant :

1. Un rédacteur modifie une page dans l’interface web du CMS (/_cms/).
2. Le CMS enregistre la modification sous forme de commit sur le dépôt Bitbucket (un fichier .md modifié).
3. Un webhook Bitbucket déclenche l’intégration continue (Jenkins), qui lance npm run build.
4. Le nouveau dist/ est déployé sur le serveur.