Skip to content
AMN Docs

[Nom de la Configuration d'Indexation Pagefind]

[Nom de la Configuration d'Indexation Pagefind]

Documentation technique

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

Source de contenu Statut
Sanity (SSG) [✅/❌]
Starlight [✅/❌]
Les deux [✅/❌]
Type d’indexation Statut
Statique au build [✅/❌]
Dynamique [✅/❌]

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

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

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

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

Terminal window
# 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]
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare