Skip to content
AMN Docs

[Nom de la Collection de Contenu]

[Nom de la Collection de Contenu]

Documentation technique

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é1/3

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

1.3. Périmètre concerné2/3

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

1.3. Périmètre concerné3/3

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.ts1/2

3.1. Définition dans src/content/config.ts2/2

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

Terminal window
# 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

14. Historique des modifications

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

Contents

Built with StarlightPowered by Cloudflare