[Nom de la Collection de Contenu]

Type de ressource : Astro Content Collection (Markdown/MDX)
Fichier source : src/content/[collection-name]/ ou src/content/config.ts
Statut : [Actif / Déprécié / En développement]
Slice : [Numéro de la tranche verticale]
Version : 1.0

---

1. Vue d’ensemble (DOC)

1.1. Description

[Description concise de cette collection de contenu et son rôle dans l’architecture du site]

1.2. Objectif

• [Objectif principal : ex. fournir une documentation technique pour les développeurs]
• [Bénéfice pour l’utilisateur final]

1.3. Périmètre concerné

Type de contenu	Statut
Documentation technique	[✅/❌]
Blog	[✅/❌]
Portfolio	[✅/❌]
Pages statiques	[✅/❌]

Format	Statut
Markdown (.md)	[✅/❌]
MDX (.mdx)	[✅/❌]
Les deux	[✅/❌]

Consommateur	Statut
Starlight	[✅/❌]
Astro SSG	[✅/❌]
Les deux	[✅/❌]

Indexation	Statut
Pagefind	[✅/❌]

---

2. Architecture et structure (DOC)

2.1. Arborescence des fichiers

src/content/
├── config.ts                    # Définition des schémas Zod
└── [collection-name]/
    ├── index.mdx                # Page d'accueil de la collection
    ├── [section-1]/
    │   ├── page-1.md
    │   └── page-2.mdx    └── [section-2]/
        └── page-3.md

2.2. Composants impliqués

Composant	Rôle	Couche
src/content/config.ts	Définition des schémas de validation (Zod)	L2 (Astro)
Fichiers MD/MDX	Contenu source	L1 (Contenu)
Starlight	Rendu de la documentation	L2 (Astro)
Pagefind	Indexation pour la recherche	L2 (Astro)
Git	Versioning et workflow de publication	Infrastructure

---

3. Configuration de la collection (CODE)

3.1. Définition dans src/content/config.ts

src/content/config.ts

import { z, defineCollection } from 'astro:content';

const [collectionName]Collection = defineCollection({
  type: 'content', // ou 'data' si JSON/YAML
  schema: ({ image }) => z.object({
    title: z.string(),
    description: z.string().optional(),
    publishedAt: z.date().optional(),
    updated: z.date().optional(),
    order: z.number().optional(),
    draft: z.boolean().optional().default(false),
    // Métadonnées spécifiques à Starlight
    sidebar: z.object({
      label: z.string(),
      order: z.number().optional(),
      badge: z.object({
        text: z.string(),
        variant: z.enum(['note', 'tip', 'caution', 'danger']).optional(),
      }).optional(),
    }).optional(),
    // Métadonnées SEO
    head: z.array(z.object({
      tag: z.enum(['title', 'meta', 'link']),
      attrs: z.record(z.string()).optional(),
      content: z.string().optional(),
    })).optional(),
    // Image de couverture (si applicable)
    cover: image().optional(),
  }),
});

export const collections = {
  [collectionName]: [collectionName]Collection,
};

3.2. Variables d’environnement (si applicable)

Variable	Description	Obligatoire	Valeur par défaut
[Variable]	[Description]	[✅/❌]	[Valeur]

---

4. Structure des fichiers Markdown/MDX (CODE)

4.1. Frontmatter requis

---
title: "Titre de la page"
description: "Description de la page"
publishedAt: 2026-09-04
draft: false
sidebar:
  label: "Label dans la sidebar"
  order: 1
---

4.2. Exemple de fichier Markdown

---
title: "Introduction"
description: "Introduction à la documentation"
sidebar:
  label: "Introduction"
  order: 1
---

# Introduction

Contenu de la documentation...

4.3. Exemple de fichier MDX

---
title: "Composants Interactifs"
description: "Utilisation des composants MDX"
sidebar:
  label: "Composants"
  order: 2
---

import { Counter } from '../components/Counter';

# Composants Interactifs

<Counter />

Contenu de la documentation...

---

5. Contrats d’Entrée/Sortie (SPEC)

5.1. Inputs (Frontmatter)

Champ	Type	Obligatoire	Validation
title	string	✅	Non vide
description	string	❌	Valeur par défaut
publishedAt	date	❌	Date valide
draft	boolean	❌	Valeur par défaut

5.2. Outputs (Contenu)

Élément	Type	Description
frontmatter	object	Métadonnées validées
body	string	Contenu Markdown/MDX

---

6. Tests attendus (TEST)

6.1. Tests unitaires

Scénario	Description	Résultat attendu
Validation Zod	Frontmatter valide	Validation réussie
Validation Zod	Frontmatter invalide	Erreur de validation

6.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Build complet	Starlight + Astro	Build de la documentation	Build réussi

6.3. Tests E2E

Scénario	Parcours utilisateur	Description	Résultat attendu
Navigation	Utilisateur → Documentation	Navigation dans la docs	Pages affichées correctement

---

7. Intégration (INTÉG)

7.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Starlight	Rendu	Rendu de la documentation	Configuration dans astro.config.mjs
Pagefind	Indexation	Indexation du contenu	Build script
Git	Versioning	Workflow de publication	Git workflow

7.2. Points d’attention

• Les schémas Zod doivent être valides
• Le frontmatter doit respecter le schéma
• Les fichiers doivent être organisés correctement

7.3. Vérification de cohérence

• Les schémas Zod sont valides
• Le build réussit
• La documentation est indexée par Pagefind
• Les tests E2E passent

---

8. Sécurité

8.1. Mécanismes de sécurité

• ✅ Validation Zod des frontmatter
• ✅ Pas d’exécution de code non sécurisé
• ✅ Git workflow sécurisé

8.2. Règles de sécurité

• ✅ Ne jamais inclure de données sensibles dans les fichiers
• ✅ Valider tous les inputs utilisateur
• ✅ Utiliser les permissions Git appropriées

---

9. Performance et limites

9.1. Optimisations

Optimisation	Description
SSG	Génération statique au build
Lazy loading	Chargement différé des composants
Image Optimization	Optimisation des images

9.2. Limitations

• ❌ Les fichiers MDX augmentent le build time
• ❌ Les composants MDX nécessitent une hydratation

---

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme	Cause probable	Solution
Validation échoue	Frontmatter invalide	Vérifier le schéma Zod
Build échoue	Erreur MDX	Vérifier la syntaxe MDX
Indexation échoue	Pagefind configuration	Vérifier la configuration Pagefind

10.2. Commandes de debug

# Build local
npm run build

# Preview du build
npm run preview

---

11. Bonnes pratiques

11.1. Architecture

• ✅ Schémas Zod typés
• ✅ Organisation hiérarchique des fichiers
• ✅ Frontmatter documenté

11.2. Code

• ✅ Utiliser des composants MDX réutilisables
• ✅ Optimiser les images
• ✅ Documenter les changements

11.3. Maintenance

• ✅ Mettre à jour les schémas régulièrement
• ✅ Documenter les changements dans ce fichier

---

12. Évolutions et roadmap

12.1. Améliorations planifiées

• [Évolution 1]
• [Évolution 2]

12.2. Limitations connues

• ❌ [Limitation 1]
• ❌ [Limitation 2]

---

13. Ressources liées

• Documentation Astro : Content Collections
• Documentation Starlight : Starlight Docs
• DAT L2 : §5.5 - Content Collections

---

14. Historique des modifications

Date	Version	Description	Auteur
YYYY-MM-DD	1.0	Création initiale	[Nom]