[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]

1. Vue d’ensemble

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 : [Documentation technique / Blog / Portfolio / Pages statiques]
• Format : [Markdown (.md) / MDX (.mdx) / Les deux]
• Consommateur : [Starlight / Astro SSG / Les deux]
• Indexation : [Pagefind ✅/❌]

2. Architecture et structure

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

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

4.1. Frontmatter requis

---
title: "Titre de la page"
description: "Description courte pour SEO et aperçu"
publishedAt: 2026-09-03
updated: 2026-09-03
order: 1
draft: false
sidebar:
  label: "Libellé dans la sidebar"
  order: 1
  badge:
    text: "Nouveau"
    variant: "tip"
head:
  - tag: meta
    attrs:
      name: "robots"
      content: "index, follow"
---

4.2. Structure du contenu

# Titre principal (H1)

Introduction ou résumé de la page.

## Section 1 (H2)

Contenu de la section.

### Sous-section (H3)

Détails ou exemples.

## Section 2 (H2)

Autre contenu.

## Voir aussi

- [Lien vers page connexe 1](./page-1.md)
- [Lien vers page connexe 2](./page-2.md)

4.3. Composants MDX (si applicable)

---
title: "Page avec composants interactifs"
---

import { CodeBlock, Callout, Tabs } from '@astrojs/starlight/components';

# Titre

<Intro>
Texte d'introduction stylisé.
</Intro>

<Callout type="tip">
Ceci est un appel important.
</Callout>

<Tabs>
  <Fragment slot="tab">Option 1</Fragment>
  <Fragment slot="panel">Contenu de l'option 1</Fragment>

  <Fragment slot="tab">Option 2</Fragment>
  <Fragment slot="panel">Contenu de l'option 2</Fragment>
</Tabs>

<CodeBlock lang="typescript">
const example = "code";
</CodeBlock>

5. Intégration avec Starlight

5.1. Configuration Starlight

astro.config.mjs

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Documentation Technique',
      sidebar: [
        {
          label: 'Guide de Démarrage',
          autogenerate: { directory: 'guide' },
        },
        {
          label: 'Références API',
          autogenerate: { directory: 'api' },
        },
        {
          label: 'Tutoriels',
          items: [
            { label: 'Installation', link: '/tutorials/installation/' },
            { label: 'Configuration', link: '/tutorials/configuration/' },
          ],
        },
      ],
    }),
  ],
});

5.2. Structure de la sidebar

Section	Dossier	Ordre	Badge
Guide de Démarrage	guide/	Auto	-
Références API	api/	Auto	-
Tutoriels	tutorials/	Manuel	-
[Autre section]	[Dossier]	[Auto/Manuel]	[Badge]

5.3. Personnalisation du thème Starlight

src/styles/starlight-overrides.css

:root {
  --sl-color-accent-low: #1e1b4b;
  --sl-color-accent: #4f46e5;
  --sl-color-accent-high: #c7d2fe;
  --sl-color-white: #ffffff;
  --sl-color-gray-1: #f8fafc;
  --sl-color-gray-2: #e2e8f0;
  --sl-color-gray-3: #cbd5e1;
  --sl-color-gray-4: #94a3b8;
  --sl-color-gray-5: #64748b;
  --sl-color-gray-6: #475569;
  --sl-color-gray-7: #334155;
  --sl-color-gray-8: #1e293b;
  --sl-color-gray-9: #0f172a;
  --sl-color-black: #020617;
}

6. Indexation Pagefind

6.1. Configuration de l’indexation

// astro.config.mjs (extrait)
import pagefind from 'astro-pagefind';

export default defineConfig({
  integrations: [
    pagefind({
      ranking: {
        pageLength: 0.1,
        termFrequency: 0.5,
        termSaturation: 0.5,
        termSimilarity: 0.9,
      },
    }),
  ],
});

6.2. Métadonnées Pagefind

---
title: "Titre de la page"
# Métadonnées Pagefind
pagefind:
  weight:
    title: 2.0
    content: 1.0
  meta:
    type: "documentation"
    category: "guide"
  filters:
    - type: documentation
    - category: guide
  exclude:
    selectors:
      - "nav"
      - "footer"
      - ".no-index"
---

6.3. Règles d’indexation

Règle	Configuration	Rationale
Inclure toutes les pages publiées	draft: false	Contenu accessible aux utilisateurs
Exclure les brouillons	draft: true	Contenu non finalisé
Exclure les éléments de navigation	exclude_selectors: ["nav", "footer"]	Éviter le bruit dans les résultats
Pondérer les titres	weight.title: 2.0	Améliorer la pertinence
Filtrer par type	filters: ["documentation"]	Permettre le filtrage dans l’UI

7. Workflow Git

7.1. Cycle de vie d’un document

[Création locale] → [Commit] → [Pull Request] → [Revue] → [Merge] → [Build] → [Déploiement]
     │                │              │              │          │          │          │
     ▼                ▼              ▼              ▼          ▼          ▼          ▼
   Rédacteur      Développeur    Équipe Tech    Reviewer    CI/CD      Astro     Cloudflare

7.2. Conventions de commit

# Types de commits recommandés
docs: ajout de la page d'installation
docs: mise à jour de la configuration API
docs: correction typo dans le guide de démarrage
docs: suppression de la page obsolète

7.3. Processus de revue

Étape	Responsable	Action
1. Rédaction	Rédacteur technique	Création du contenu MD/MDX
2. Validation technique	Développeur	Vérification de l’exactitude technique
3. Revue éditoriale	Éditeur	Vérification de la clarté et du style
4. Merge	Mainteneur	Intégration dans la branche principale
5. Déploiement	CI/CD	Build Astro + déploiement Cloudflare Pages

8. Sécurité et validation

8.1. Validation des schémas

• ✅ Tous les fichiers MD/MDX doivent respecter le schéma Zod défini dans config.ts
• ✅ Le build Astro échoue si un fichier ne valide pas le schéma
• ✅ Les champs obligatoires sont : title
• ✅ Les dates doivent être au format ISO 8601

8.2. Règles de sécurité

• ✅ Aucun secret ou information sensible ne doit être inclus dans les fichiers MD/MDX
• ✅ Les liens externes doivent être vérifiés (pas de broken links)
• ✅ Les images doivent être optimisées et stockées dans R2 (pas dans Git)
• ✅ Le contenu doit être relu avant publication

8.3. Protection des branches

• ✅ La branche main est protégée (merge via PR uniquement)
• ✅ Au moins une approbation requise avant merge
• ✅ Les checks CI doivent passer (lint, build, tests)

9. Performance et optimisation

9.1. Optimisation des images

• ✅ Utiliser des images WebP/AVIF (conversion automatique via Cloudflare)
• ✅ Dimensions maximales : 1920x1080 pour les images de contenu
• ✅ Poids maximal : 500 KB par image
• ✅ Toujours fournir alt descriptif

9.2. Optimisation du contenu

• ✅ Limiter la taille des fichiers MD/MDX à 50 KB
• ✅ Découper les contenus longs en plusieurs pages
• ✅ Utiliser des ancres pour la navigation intra-page
• ✅ Éviter les composants MDX trop lourds

9.3. Performance de build

• ⚠️ Le build Astro peut être lent avec beaucoup de fichiers MDX (> 100)
• ⚠️ Les composants MDX complexes augmentent le temps de build
• ✅ Utiliser getCollection() pour précharger les données
• ✅ Mettre en cache les résultats de build si possible

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme	Cause probable	Solution
“Schema validation failed”	Frontmatter incorrect	Vérifier le schéma Zod dans config.ts
Page non visible dans Starlight	draft: true ou mauvais dossier	Vérifier le frontmatter et l’emplacement
Sidebar mal ordonnée	order manquant ou incorrect	Ajouter/corriger le champ order
Liens cassés	Chemin relatif incorrect	Vérifier les liens (utiliser ./ pour relatif)
Build échoue	Syntaxe MDX invalide	Vérifier la syntaxe des composants MDX
Pagefind n’indexe pas	draft: true ou exclusion	Vérifier le frontmatter et la config Pagefind

10.2. Logs et monitoring

# Logs de build Astro
npm run build -- --verbose

# Vérification des schémas
npx astro check

# Test de l'indexation Pagefind
npx pagefind --source dist

10.3. Tests manuels

# Test local
npm run dev

# Vérification des liens
npx broken-link-checker http://localhost:4321

# Validation de l'accessibilité
npx axe http://localhost:4321/docs/

11. Bonnes pratiques

11.1. Rédaction

• ✅ Utiliser un langage clair et concis
• ✅ Structurer avec des titres hiérarchiques (H1, H2, H3)
• ✅ Inclure des exemples de code quand pertinent
• ✅ Ajouter des captures d’écran pour les interfaces
• ✅ Fournir des liens vers des ressources connexes

11.2. Organisation

• ✅ Regrouper les pages par thème dans des dossiers
• ✅ Utiliser des noms de fichiers descriptifs (kebab-case)
• ✅ Maintenir une page d’index (index.md) par dossier
• ✅ Documenter la structure dans un fichier README.md

11.3. Maintenance

• ✅ Mettre à jour les dates (updated) lors des modifications
• ✅ Archiver les contenus obsolètes plutôt que les supprimer
• ✅ Vérifier régulièrement les liens cassés
• ✅ Revoir le contenu tous les 6 mois

11.4. Accessibilité

• ✅ Utiliser des textes alternatifs descriptifs pour les images
• ✅ Assurer un contraste suffisant (WCAG AA minimum)
• ✅ Structurer le contenu avec des titres hiérarchiques
• ✅ Fournir des transcripts pour les vidéos

12. Évolutions et roadmap

12.1. Améliorations planifiées

• [Évolution 1 : ex. Ajout de la recherche full-text avec Pagefind]
• [Évolution 2 : ex. Support du multi-langue (i18n)]
• [Évolution 3 : ex. Intégration de composants interactifs avancés]

12.2. Limitations connues

• ❌ Les fichiers MDX ne peuvent pas être édités dans Sanity (Git uniquement)
• ❌ Le build peut être lent avec beaucoup de composants MDX
• ❌ Les images doivent être optimisées manuellement avant commit

13. Ressources liées

• Documentation Astro : Content Collections
• Documentation Starlight : Getting Started
• Documentation Pagefind : Getting Started
• DAT L1 : §3.2 - Composant Fichiers Locaux : Astro Starlight
• DAT L2 : §5.2 - Isolation de la Documentation (Starlight)
• DAT L2 : §8 - Stratégie de Recherche Unifiée (Pagefind)
• Fichiers concernés :
  • src/content/config.ts
  • src/content/[collection-name]/**/*.md
  • src/content/[collection-name]/**/*.mdx
  • astro.config.mjs

14. Historique des modifications

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

---

**Points clés de ce template :**
- Documente la structure des content collections Astro (MD/MDX)
- Inclut la configuration Starlight et l'indexation Pagefind
- Détaille le workflow Git (critique pour ce type de contenu)
- Fournit des bonnes pratiques de rédaction et d'organisation
- Sépare clairement la configuration, le contenu, et l'indexation
- Inclut un guide de débogage complet