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]

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

Terminal window
# 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

Terminal window
# 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ées1/2

  • 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)

13. Ressources liées2/2

  • 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 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 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
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare