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

1. Vue d’ensemble

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é

• Sources de contenu : [Sanity (SSG) / Starlight / Les deux]
• Type d’indexation : [Statique au build / Dynamique / Les deux]
• Langues supportées : [fr / en / multi-langue]
• Couverture : [Vitrine / Blog / Portfolio / Documentation / Tout]

2. Architecture et flux

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

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
include_patterns:
  - '**/*.html'
exclude_patterns:
  - '**/api/**'
  - '**/preview/**'
  - '**/404.html'
  - '**/500.html'
ranking:
  pageLength: 0.1
  termFrequency: 0.5
  termSaturation: 0.5
  termSimilarity: 0.9

3.3. Commandes npm

package.json

{
  "scripts": {
    "build": "astro build && pagefind --source dist",
    "build:search": "pagefind --source dist",
    "dev": "astro dev"
  }
}

4. Règles d’inclusion et d’exclusion

4.1. Pages incluses

Type de page	Source	Inclusion	Rationale
Pages vitrine	Sanity (SSG)	✅	Contenu public
Articles de blog	Sanity (SSG)	✅	Contenu public
Projets portfolio	Sanity (SSG)	✅	Contenu public
Documentation	Starlight	✅	Contenu technique
Pages d’accueil	Sanity (SSG)	✅	Contenu public

4.2. Pages exclues

Type de page	Raison d’exclusion	Méthode
Pages API (/api/*)	Routes techniques	Pattern **/api/**
Pages Preview	Contenu draft	Cookie/header detection
Pages d’erreur (404, 500)	Non pertinentes	Pattern **/404.html
Routes administratives	Accès restreint	Pattern **/admin/**
Pages de formulaire (GET)	Pas de contenu indexable	Classe .no-index
Éléments de navigation	Bruit dans les résultats	Sélecteur nav
Footer	Bruit dans les résultats	Sélecteur footer

4.3. Exclusion via attributs HTML

<!-- Exclure un élément spécifique de l'indexation -->
<div data-pagefind-ignore="all">
  <!-- Contenu non indexé -->
</div>

<!-- Exclure uniquement le contenu texte (conserver les liens) -->
<div data-pagefind-ignore="content">
  <!-- Texte non indexé, mais liens indexés -->
</div>

<!-- Exclure via classe CSS -->
<div class="no-index">
  <!-- Contenu non indexé -->
</div>

5. Métadonnées et filtres

5.1. Métadonnées Pagefind

---
title: "Titre de la page"
description: "Description de la page"
# Métadonnées Pagefind spécifiques
pagefind:
  weight:
    title: 2.0        # Poids du titre dans le ranking
    content: 1.0      # Poids du contenu
  meta:
    type: "blog"      # Type de contenu (pour filtrage)
    category: "tech"  # Catégorie (pour filtrage)
    author: "John Doe" # Auteur (pour filtrage)
  filters:
    - type: blog
    - category: tech
    - author: john-doe
  exclude:
    selectors:
      - ".sidebar"
      - ".related-posts"
---

5.2. Métadonnées via attributs HTML

<!-- Définir des métadonnées Pagefind -->
<article data-pagefind-meta="type:blog,category:tech,author:john-doe">
  <h1 data-pagefind-weight="2.0">Titre de l'article</h1>
  <div data-pagefind-body>
    <!-- Contenu principal -->
  </div>
</article>

5.3. Filtres disponibles

Filtre	Type	Exemple de valeurs	Usage
type	String	blog, portfolio, docs, page	Distinction visuelle des résultats
category	String	tech, design, marketing	Filtrage par catégorie
author	String	john-doe, jane-smith	Filtrage par auteur
language	String	fr, en	Filtrage par langue (i18n)
date	Date	2026-09-03	Tri chronologique

6. Intégration avec Starlight

6.1. Configuration Starlight

astro.config.mjs

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Documentation Technique',
      // Starlight utilise Pagefind nativement
      // L'index est partagé avec le reste du site
    }),
  ],
});

6.2. Cohérence des index

• ✅ Starlight et le site principal partagent le même index Pagefind
• ✅ Les pages de documentation sont indexées avec les mêmes règles
• ✅ Les filtres permettent de distinguer les résultats (badge “Doc”)
• ✅ L’expérience de recherche est homogène sur tout le site

6.3. Métadonnées Starlight

---
title: "Guide d'installation"
description: "Comment installer et configurer le projet"
sidebar:
  label: "Installation"
  order: 1
# Métadonnées Pagefind pour Starlight
pagefind:
  meta:
    type: "docs"
    category: "guide"
  filters:
    - type: docs
    - category: guide
---

7. Stratégie de ranking

7.1. Paramètres de ranking

Paramètre	Valeur	Description
pageLength	0.1	Pénalité pour les pages trop longues
termFrequency	0.5	Importance de la fréquence des termes
termSaturation	0.5	Saturation de la fréquence des termes
termSimilarity	0.9	Tolérance aux fautes de frappe

7.2. Pondération des éléments

Élément	Poids	Rationale
Titre (<h1>)	2.0	Plus important que le contenu
Sous-titres (<h2>, <h3>)	1.5	Importance intermédiaire
Contenu principal	1.0	Poids standard
Métadonnées (title, description)	1.5	Importance élevée
Liens et navigation	0.5	Poids réduit

7.3. Personnalisation du ranking

<!-- Augmenter le poids d'un titre spécifique -->
<h1 data-pagefind-weight="3.0">Titre très important</h1>

<!-- Réduire le poids d'une section -->
<section data-pagefind-weight="0.5">
  <!-- Contenu moins important -->
</section>

8. Performance et optimisation

8.1. Taille de l’index

Métrique	Objectif	Stratégie
Taille totale	< 5 MB	Exclusion des éléments non pertinents
Temps d’indexation	< 30s	Optimisation des règles d’exclusion
Temps de chargement	< 500ms	Index chunké (lazy loading)
Mémoire client	< 50 MB	Pagination des résultats

8.2. Optimisation de l’index

• ✅ Exclure les éléments de navigation et footer (réduit le bruit)
• ✅ Utiliser des sélecteurs CSS précis pour exclure du contenu
• ✅ Limiter les métadonnées aux filtres réellement utilisés
• ✅ Optimiser les images avant le build (réduit la taille HTML)
• ✅ Utiliser data-pagefind-body pour identifier le contenu principal

8.3. Index chunké

Pagefind génère un index fragmenté (chunks) qui est chargé à la demande :

_pagefind/
├── pagefind.js          # Script principal
├── pagefind-ui.css      # Styles UI (optionnel)
├── fragment/
│   ├── pagefind.pf_1    # Chunk 1
│   ├── pagefind.pf_2    # Chunk 2
│   └── ...
└── metadata/
    └── pagefind.pf_meta # Métadonnées

9. Intégration avec l’UI de recherche

9.1. Composant de recherche

src/components/ui/SearchBar.astro

---
import { Search } from 'pagefind-ui';
---

<div id="search"></div>

<script>
  import { Search } from 'pagefind-ui';

  new Search({
    element: '#search',
    pageSize: 10,
    showSubResults: true,
    showImages: false,
    processResult: (result) => {
      // Personnalisation des résultats
      return {
        ...result,
        badge: result.meta.type === 'docs' ? 'Doc' :
               result.meta.type === 'blog' ? 'Blog' :
               result.meta.type === 'portfolio' ? 'Portfolio' : 'Page',
      };
    },
  });
</script>

9.2. Distinction visuelle des résultats

Type de contenu	Badge	Couleur
Documentation	“Doc”	Bleu
Article de blog	“Blog”	Vert
Projet portfolio	“Portfolio”	Orange
Page vitrine	“Page”	Gris

9.3. Filtrage par type

src/components/ui/SearchFilters.astro

<div class="search-filters">
  <label>
    <input type="checkbox" value="docs" checked />
    Documentation
  </label>
  <label>
    <input type="checkbox" value="blog" checked />
    Blog
  </label>
  <label>
    <input type="checkbox" value="portfolio" checked />
    Portfolio
  </label>
  <label>
    <input type="checkbox" value="page" checked />
    Pages
  </label>
</div>

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme	Cause probable	Solution
Page non trouvée dans les résultats	Page exclue ou non publiée	Vérifier les règles d’exclusion et le statut
Résultats non pertinents	Ranking mal configuré	Ajuster les poids et les métadonnées
Index trop volumineux	Trop de contenu indexé	Exclure les éléments non pertinents
Recherche lente	Index non optimisé	Réduire la taille de l’index
Filtres non fonctionnels	Métadonnées manquantes	Ajouter les métadonnées Pagefind
Starlight non indexé	Configuration incorrecte	Vérifier l’intégration Starlight

10.2. Tests manuels

# Génération de l'index
npm run build:search

# Vérification de l'index
ls -lh dist/_pagefind/

# Test de la recherche en local
npm run preview
# Ouvrir http://localhost:4321 et tester la recherche

# Inspection de l'index (debug)
npx pagefind --source dist --verbose

10.3. Logs et monitoring

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

# Logs Pagefind
npx pagefind --source dist --verbose

# Vérification de la taille de l'index
du -sh dist/_pagefind/

11. Bonnes pratiques

11.1. Configuration

• ✅ Exclure systématiquement les éléments de navigation et footer
• ✅ Utiliser des sélecteurs CSS précis pour les exclusions
• ✅ Définir des métadonnées cohérentes pour tous les types de contenu
• ✅ Tester l’indexation après chaque modification majeure
• ✅ Documenter les règles d’exclusion dans ce fichier

11.2. Contenu

• ✅ Utiliser une structure HTML sémantique (<h1>, <h2>, <article>)
• ✅ Identifier le contenu principal avec data-pagefind-body
• ✅ Fournir des titres descriptifs et uniques
• ✅ Éviter le contenu dupliqué entre pages
• ✅ Optimiser les images avant le build

11.3. Performance

• ✅ Surveiller la taille de l’index (objectif < 5 MB)
• ✅ Optimiser le ranking pour les contenus prioritaires
• ✅ Utiliser l’index chunké pour le lazy loading
• ✅ Tester les performances de recherche sur mobile
• ✅ Mesurer les Core Web Vitals avec la recherche active

11.4. Maintenance

• ✅ Régénérer l’index à chaque build (automatique)
• ✅ Vérifier les résultats de recherche après publication
• ✅ Ajuster les règles d’exclusion si nécessaire
• ✅ Documenter les changements de configuration
• ✅ Tester les filtres et les métadonnées régulièrement

12. Évolutions et roadmap

12.1. Améliorations planifiées

• [Évolution 1 : ex. Support du multi-langue (i18n)]
• [Évolution 2 : ex. Recherche facette avancée]
• [Évolution 3 : ex. Suggestions de recherche (autocomplete)]

12.2. Limitations connues

• ❌ Pagefind ne supporte pas nativement la recherche dynamique (SSR)
• ❌ L’index doit être régénéré à chaque build (pas de mise à jour incrémentale)
• ❌ Les filtres sont limités aux métadonnées définies au build
• ❌ La recherche full-text ne supporte pas nativement les langues non-latines

13. Ressources liées

• Documentation Pagefind : Getting Started
• Documentation Pagefind : Indexing
• Documentation Pagefind : Search UI
• Documentation astro-pagefind : npm package
• DAT L2 : §8 - Stratégie de Recherche Unifiée (Pagefind)
• DAT L2 : §5.2 - Isolation de la Documentation (Starlight)
• Fichiers concernés :
  • astro.config.mjs
  • pagefind.yml (si applicable)
  • src/components/ui/SearchBar.astro
  • src/components/ui/SearchFilters.astro
  • dist/_pagefind/ (généré au build)

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 configuration complète de l'indexation Pagefind
- Détaille les règles d'inclusion et d'exclusion (critique pour la pertinence)
- Inclut l'intégration avec Starlight (index partagé)
- Fournit la stratégie de ranking et de pondération
- Couvre les métadonnées et les filtres (distinction visuelle des résultats)
- Sépare clairement la configuration, le contenu, et l'UI
- Inclut les bonnes pratiques de performance et de maintenance