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

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`1/2

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

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

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/' },
          ],
        },
      ],
    }),
  ],
});

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

: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ées1/2

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)

13. Ressources liées2/2

Fichiers concernés :
- src/content/config.ts
- src/content/[collection-name]/**/*.md
- src/content/[collection-name]/**/*.mdx
- astro.config.mjs

14. Historique des modifications1/2

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

14. Historique des modifications2/2

---

**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

[Nom de la Collection de Contenu]

[Nom de la Collection de Contenu]

1. Vue d’ensemble

1.1. Description

1.2. Objectif

1.3. Périmètre concerné

2. Architecture et structure

2.1. Arborescence des fichiers

2.2. Composants impliqués

3. Configuration de la collection

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

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

3.2. Variables d’environnement (si applicable)

4. Structure des fichiers Markdown/MDX

4.1. Frontmatter requis

4.2. Structure du contenu

4.3. Composants MDX (si applicable)

5. Intégration avec Starlight

5.1. Configuration Starlight

5.2. Structure de la sidebar

5.3. Personnalisation du thème Starlight

6. Indexation Pagefind

6.1. Configuration de l’indexation

6.2. Métadonnées Pagefind

6.3. Règles d’indexation

7. Workflow Git

7.1. Cycle de vie d’un document

7.2. Conventions de commit

7.3. Processus de revue

8. Sécurité et validation

8.1. Validation des schémas

8.2. Règles de sécurité

8.3. Protection des branches

9. Performance et optimisation

9.1. Optimisation des images

9.2. Optimisation du contenu

9.3. Performance de build

10. Débogage et troubleshooting

10.1. Problèmes courants

10.2. Logs et monitoring

10.3. Tests manuels

11. Bonnes pratiques

11.1. Rédaction

11.2. Organisation

11.3. Maintenance

11.4. Accessibilité

12. Évolutions et roadmap

12.1. Améliorations planifiées

12.2. Limitations connues

13. Ressources liées1/2

13. Ressources liées2/2

14. Historique des modifications1/2

14. Historique des modifications2/2

3.1. Définition dans `src/content/config.ts`1/2

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