[Nom de la Configuration d'Indexation Pagefind]

Type de ressource : Configuration Indexation Pagefind (Règles / Exclusions / Métadonnées)
Fichier source : astro.config.mjs ou pagefind.yml
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 du rôle de cette configuration d’indexation dans l’architecture du site]

1.2. Objectif

• [Objectif principal : ex. indexer uniquement les pages publiées du blog et de la documentation]
• [Bénéfice pour l’utilisateur final : ex. recherche rapide et pertinente]

1.3. Périmètre concerné

Source de contenu	Statut
Sanity (SSG)	[✅/❌]
Starlight	[✅/❌]
Les deux	[✅/❌]

Type d’indexation	Statut
Statique au build	[✅/❌]
Dynamique	[✅/❌]

Langues	Statut
fr	[✅/❌]
en	[✅/❌]
multi-langue	[✅/❌]

Couverture	Statut
Vitrine	[✅/❌]
Blog	[✅/❌]
Portfolio	[✅/❌]
Documentation	[✅/❌]
Tout	[✅/❌]

---

2. Architecture et flux (DOC)

2.1. Diagramme de flux

[Build Astro (SSG)]
     │  • Génération HTML statique
     │  • Pages Sanity + Starlight
     ▼
[Pagefind CLI / astro-pagefind]
     │  • Lecture du dossier dist/
     │  • Application des règles d'exclusion
     │  • Extraction du contenu texte
     │  • Génération de l'index chunké
     ▼
[Dossier _pagefind/]
     │  • Index fragmenté (chunks)
     │  • Métadonnées et filtres
     ▼
[Site déployé]
     │  • Index chargé à la demande
     │  • Recherche côté client
     ▼
[Utilisateur final]

2.2. Composants impliqués

Composant	Rôle	Couche
Astro (SSG)	Génération des pages HTML	L2
Pagefind CLI	Indexation statique	Build time
astro-pagefind	Intégration Astro	L2
Starlight	Documentation indexée	L2
Index Pagefind	Stockage de l’index	Build artifact
UI de recherche	Interface utilisateur	L2

---

3. Configuration de l’indexation (CODE)

3.1. Configuration dans astro.config.mjs

astro.config.mjs

import pagefind from 'astro-pagefind';

export default defineConfig({
  integrations: [
    pagefind({
      ranking: {
        pageLength: 0.1,
        termFrequency: 0.5,
        termSaturation: 0.5,
        termSimilarity: 0.9,
      },
      excludeSelectors: [
        'nav',
        'footer',
        '.no-index',
        '.search-exclude',
        'script',
        'style',
      ],
    }),
  ],
});

3.2. Configuration alternative : pagefind.yml

# pagefind.yml (à la racine du projet)
site: dist
exclude_selectors:
  - nav
  - footer
  - .no-index
  - .search-exclude
  - script
  - style

3.3. Métadonnées personnalisées

---
// Dans les pages Astro
const pagefindMeta = {
  type: 'blog', // ou 'page', 'portfolio', 'docs'
  category: 'marketing',
  date: '2026-09-04',
};
---
<html data-pagefind-meta={JSON.stringify(pagefindMeta)}>

---

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

4.1. Inputs (HTML généré)

Élément	Type	Validation
dist/	Directory	Existe et contient HTML

4.2. Outputs (Index)

Élément	Type	Description
_pagefind/	Directory	Index chunké
pagefind.wasm	File	WebAssembly

---

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Indexation	Build complet	Index généré
Exclusions	Sélecteurs appliqués	Éléments exclus

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Recherche	Index + UI	Recherche d’un terme	Résultats pertinents

---

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Astro	L2	Génération HTML	astro-pagefind
Starlight	L2	Documentation	Indexation automatique

6.2. Points d’attention

• Les sélecteurs d’exclusion doivent être corrects
• Les métadonnées doivent être cohérentes
• L’index doit être régénéré après chaque build

6.3. Vérification de cohérence

• L’index est généré au build
• Les exclusions sont appliquées
• Les métadonnées sont accessibles
• La recherche fonctionne

---

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Pas d’exposition de données sensibles
• ✅ Index côté client uniquement

7.2. Règles de sécurité

• ✅ Exclure les zones sensibles
• ✅ Ne pas indexer les pages privées

---

8. Performance et limites

8.1. Limites Pagefind

Limite	Valeur
Taille de l’index	~10 MB par 10 000 pages
Temps d’indexation	~30s pour 10 000 pages

8.2. Optimisations

• ✅ Index chunké (chargement progressif)
• ✅ WebAssembly
• ✅ Compression

---

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Index vide	Build échoué	Vérifier le build
Résultats manquants	Exclusions trop larges	Ajuster les sélecteurs

9.2. Commandes de debug

# Build avec Pagefind
npm run build

# Test local
npm run preview

---

10. Bonnes pratiques

10.1. Architecture

• ✅ Exclure les éléments non pertinents
• ✅ Utiliser des métadonnées cohérentes
• ✅ Tester la recherche après chaque build

10.2. Maintenance

• ✅ Surveiller la taille de l’index
• ✅ Ajuster les règles d’exclusion

---

11. Évolutions et roadmap

11.1. Améliorations planifiées

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

11.2. Limitations connues

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

---

12. Ressources liées

• Documentation Pagefind : Pagefind Docs
• DAT L2 : §8 - Recherche Unifiée avec Pagefind

---

13. Historique des modifications

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