Configuration

Toute la configuration du site tient dans un seul fichier à la racine : astro.config.mjs. Voici son contenu actuel (il est importé directement depuis le projet, donc toujours à jour) :

astro.config.mjs

// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

// https://astro.build/config
export default defineConfig({
  // Sortie 100 % statique (valeur par défaut d'Astro, explicitée ici)
  output: 'static',
  integrations: [
    starlight({
      title: 'Doc Proto',
      // Feuille de style chargée sur toutes les pages
      customCss: ['./src/styles/custom.css'],
      // Composant remplacé : affiche la fiche des pages de la section CMS
      components: { MarkdownContent: './src/components/MarkdownContent.astro' },
      // Langues du site : le français à la racine (/guides/…), l'anglais sous /en/ (/en/guides/…).
      // Une page anglaise a le même chemin que la page française, préfixé par en/.
      // Une page non traduite affiche le contenu français avec un avertissement.
      defaultLocale: 'root',
      locales: {
        root: { label: 'Français', lang: 'fr' },
        en: { label: 'English', lang: 'en' },
      },
      sidebar: [
        {
          label: 'Guides',
          // Toutes les pages de src/content/docs/guides/ apparaissent automatiquement
          items: [{ autogenerate: { directory: 'guides' } }],
        },
        {
          label: 'Comprendre Astro & Starlight',
          translations: { en: 'Understanding Astro & Starlight' },
          items: [{ autogenerate: { directory: 'concepts' } }],
        },
        {
          label: 'CMS',
          items: [{ autogenerate: { directory: 'cms' } }],
        },
        {
          label: 'Référence',
          translations: { en: 'Reference' },
          items: [{ autogenerate: { directory: 'reference' } }],
        },
        {
          label: 'Annexes',
          translations: { en: 'Appendix' },
          items: [
            // La génération automatique de 'appendix' inclurait aussi le sous-dossier examples/
            // (sous son nom brut) : les pages de premier niveau sont donc listées une par une.
            { slug: 'appendix/i18n' },
            { slug: 'appendix/helm' },
            // Sous-groupe : libellé traduit, pages de appendix/examples/ générées automatiquement
            {
              label: 'Exemple de sous-groupe',
              translations: { en: 'Sub-group example' },
              collapsed: true,
              items: [{ autogenerate: { directory: 'appendix/examples' } }],
            },
          ],
        },
      ],
    }),
  ],
});

Les éléments, un par un

defineConfig(...)

Fonction d’Astro qui encadre la configuration. Elle ne fait rien de particulier à l’exécution, mais elle permet à l’éditeur de proposer l’autocomplétion et de signaler les erreurs. Le commentaire // @ts-check en tête de fichier active cette vérification.

output: 'static'

Demande à Astro de produire un site entièrement statique : toutes les pages sont générées en HTML au moment du build. C’est la valeur par défaut ; elle est écrite ici pour être explicite. (L’alternative, 'server', générerait les pages à la demande et nécessiterait un serveur Node.js.)

integrations: [starlight({...})]

La liste des intégrations, c’est-à-dire des extensions d’Astro. Starlight est la seule ici. Tout ce qui est entre les accolades de starlight(...) est la configuration de Starlight.

title

Le nom du site, affiché en haut à gauche et ajouté au titre de chaque onglet du navigateur (« Configuration | Doc Proto »).

locales

Déclare les langues du site. Le français est placé à la racine (root, avec defaultLocale: 'root') : ses URL n’ont pas de préfixe /fr/. L’anglais (en) est placé sous /en/, et ses pages dans src/content/docs/en/. Conséquences visibles : un sélecteur de langue dans l’en-tête, et l’interface de Starlight (« Rechercher » / « Search », « Sur cette page » / « On this page »…) traduite dans chaque langue.

Le fonctionnement complet est décrit dans l’annexe sur l’internationalisation.

components

Remplace un composant de Starlight par une version personnalisée. Ici, MarkdownContent (le conteneur du contenu de la page) est remplacé par src/components/MarkdownContent.astro, qui affiche la fiche des pages de la section CMS avant leur contenu, puis délègue le reste au composant d’origine.

sidebar

Décrit la barre latérale de gauche. Chaque entrée est un groupe avec un label (le titre affiché), sa traduction éventuelle (translations: { en: '…' }) et des items. Les items peuvent être :

Forme	Effet
{ autogenerate: { directory: 'guides' } }	Liste automatiquement toutes les pages du dossier guides/
{ slug: 'guides/getting-started' }	Lien vers une page précise (son titre est repris)
{ label: 'Astro', link: 'https://astro.build' }	Lien libre, éventuellement externe
{ label: 'Sous-groupe', items: [...] }	Groupe imbriqué

Ce site utilise autogenerate partout : ajouter un fichier dans un dossier suffit à le faire apparaître dans le menu, ce qui permet aux pages créées depuis Decap CMS d’apparaître sans toucher à la configuration.

Options utiles non utilisées (pour l’instant)

Option	Rôle
site: 'https://doc.exemple.com' (au niveau d’Astro)	URL publique ; active la génération du sitemap.xml et les URL canoniques
base: '/docs' (au niveau d’Astro)	Si le site est servi dans un sous-dossier
logo: { src: './src/assets/logo.svg' }	Logo dans l’en-tête
social: [{ icon: 'github', label: 'GitHub', href: '…' }]	Icônes de liens dans l’en-tête
editLink: { baseUrl: '…' }	Lien « Modifier cette page » en bas de chaque page
customCss: ['./src/styles/custom.css']	Feuille de style pour personnaliser couleurs et polices
lastUpdated: true	Affiche la date de dernière modification (lue dans Git)

Toute modification de ce fichier redémarre automatiquement le serveur de développement.