Collections de contenu

Le principe

Une collection est un ensemble de fichiers de même nature, décrit une fois pour toutes : où ils se trouvent et quelle forme ils doivent avoir. Astro peut alors les charger, les valider et générer leurs types.

Starlight utilise une collection nommée docs. Elle est déclarée dans src/content.config.ts :

src/content.config.ts

import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({
    loader: docsLoader(),
    schema: docsSchema({
      extend: z.object({
        // Nom du fichier saisi dans Decap CMS à la création d'une page (voir public/_cms/config.yml).
        // Sans effet sur le site : déclaré ici pour être documenté et validé.
        fichier: z.string().optional(),
        // Fiche descriptive des pages de la section « CMS », affichée en tête de page
        // par src/components/MarkdownContent.astro.
        fiche: z
          .object({
            site: z.url().optional(),
            github: z.url().optional(),
            licence: z.string().optional(),
            modele: z.string().optional(),
            bitbucket: z.string().optional(),
          })
          .optional(),
      }),
    }),
  }),
};

Trois éléments :

• docs: — le nom de la collection. Starlight attend précisément ce nom.
• loader: docsLoader() — où sont les fichiers. Ce chargeur fourni par Starlight lit tous les .md et .mdx de src/content/docs/, récursivement.
• schema: docsSchema() — quelle forme doit avoir chaque page. Ce schéma fourni par Starlight décrit les champs autorisés dans le frontmatter.

Le frontmatter

Le frontmatter est le bloc d’en-tête d’un fichier Markdown, encadré par ---, écrit en YAML. Il contient les métadonnées de la page, tandis que le reste du fichier en est le contenu :

src/content/docs/guides/getting-started.md

---
title: Démarrage                         # obligatoire : titre (h1 + onglet du navigateur)
description: Créer, compiler et servir.  # recommandé : balise <meta> pour les moteurs de recherche
sidebar:
  order: 1                               # position dans la barre latérale
---

Ici commence le contenu en Markdown…

La liste complète des champs est dans la référence du frontmatter.

La validation

Le schéma est appliqué à chaque compilation. Si une page ne le respecte pas, le build échoue avec un message explicite. Par exemple, une page sans title :

[InvalidContentEntryDataError] docs → guides/sans-titre data does not match collection schema.
  title: Required

C’est un garde-fou précieux : impossible de publier une page mal formée par inadvertance.

Lien avec Decap CMS

Decap CMS a son propre fichier de configuration (public/_cms/config.yml) qui décrit les champs du formulaire d’édition (titre, description, ordre…). Il faudra le garder cohérent avec ce schéma : le CMS présente le formulaire, et le schéma d’Astro vérifie le résultat au build.

Étendre le schéma

On peut ajouter ses propres champs. Par exemple, pour un champ auteur facultatif :

src/content.config.ts

import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({
    loader: docsLoader(),
    schema: docsSchema({ extend: z.object({ auteur: z.string().optional() }) }),
  }),
};

z vient de Zod, la bibliothèque de validation utilisée par Astro.