Pagefind pour la recherche d'un site statique, et comparaison avec AdSense pour la recherche
L'essentiel
- Pagefind est une bibliothèque de recherche sous licence MIT qui indexe le HTML généré une fois le générateur de site statique terminé, puis sert la recherche uniquement à partir de fichiers statiques, sans serveur.
- La version 1.6.0 était la version courante en novembre 2026 ; depuis la version 1.5, le Component UI (pagefind-modal et les composants web associés) est l'interface recommandée, tandis que l'ancien Default UI reste pris en charge.
- Pagefind indique qu'un site de 10 000 pages peut être interrogé avec moins de 300 ko de charge réseau totale, plutôt autour de 100 ko pour la plupart des sites.
- Les attributs data-pagefind-body et data-pagefind-ignore gardent menus, pieds de page et emplacements publicitaires hors de l'index, ce que la rédaction a vérifié sur un site de test.
- Programmable Search Engine est l'alternative de Google : gratuit, financé par la publicité et monétisable avec AdSense, tandis que la Custom Search JSON API est fermée aux nouveaux clients.

Pagefind ajoute une recherche plein texte à un site statique sans serveur : il lit le HTML généré une fois le générateur terminé et écrit un index de recherche fragmenté à côté. Il est gratuit, sous licence MIT, et compatible avec tout générateur statique. Pour un site AdSense, c’est l’alternative sans publicité ni API au Programmable Search Engine de Google, qui peut afficher des annonces de recherche via AdSense pour la recherche.
Pourquoi un site statique a besoin d’un autre type de recherche
Un site statique (Astro, Hugo, Eleventy, Jekyll, HTML pur) n’a aucune base de données à interroger. Les options habituelles sont :
- Un service de recherche hébergé, payant ou qui affiche ses propres publicités.
- Le Programmable Search Engine de Google, gratuit et financé par la publicité.
- Un index côté client livré avec le site. Pagefind appartient à cette catégorie.
La page d’accueil de Pagefind explique que l’index est découpé en fragments, de sorte qu’une recherche n’en charge qu’un petit sous-ensemble. Elle indique qu’un site de 10 000 pages peut être interrogé avec une charge réseau totale inférieure à 300 ko, bibliothèque comprise, et « plus proche de 100 ko » pour la plupart des sites. C’est l’affirmation du projet lui-même : mesurez-la sur votre site.
Le code est sur GitHub sous licence MIT, et la version 1.6.0 était la version courante sur npm au moment de la rédaction de ce guide.
Étape 1 : ajouter l’interface de recherche
Le guide de démarrage ajoute d’abord l’interface, afin qu’elle existe dans le site généré quand Pagefind l’indexe. Depuis la version 1.5, l’interface recommandée est le Component UI, un ensemble de composants web :
<link href="/pagefind/pagefind-component-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-component-ui.js" type="module"></script>
<pagefind-modal-trigger></pagefind-modal-trigger>
<pagefind-modal></pagefind-modal>
Ces deux fichiers n’existent pas encore : Pagefind les crée dans /pagefind/ lors de l’indexation du site. La documentation présente aussi d’autres composants (pagefind-searchbox, pagefind-input, pagefind-results, pagefind-filter-pane et d’autres) si vous préférez une page de recherche intégrée à une fenêtre modale. L’ancien « Default UI » (new PagefindUI({ element: "#search" })) reste documenté et pris en charge, mais n’est plus la recommandation principale ; de nombreux tutoriels anciens le montrent encore.
Étape 2 : indexer le site généré
Compilez votre site, puis lancez Pagefind sur le dossier de sortie :
npx -y pagefind --site dist
Utilisez le dossier dans lequel écrit votre générateur (dist pour Astro, public pour Hugo, _site pour Eleventy). Ajoutez --serve pour prévisualiser le résultat en local. La documentation présente aussi un enrobage Python (python3 -m pip install 'pagefind[extended]') et des binaires précompilés.
Dans un projet, enchaînez la commande après la compilation dans package.json :
{
"scripts": {
"build": "astro build && pagefind --site dist"
}
}
Cela suppose que pagefind soit installé comme dépendance de développement (npm install -D pagefind).
Ce que la rédaction a obtenu lors de son test
La commande npx -y pagefind@1.6.0 --site dist a été lancée sur un site de test de trois pages, dont l’une contenait un emplacement publicitaire entouré de data-pagefind-ignore. Sortie abrégée :
Running Pagefind v1.6.0 (Extended)
Found 3 files matching **/*.{html}
Found a data-pagefind-body element on the site.
↳ Ignoring pages without this tag.
Discovered 1 language: en
Indexed 3 pages
Indexed 21 words
Indexed 1 filter
Finished in 0.295 seconds
Le dossier de sortie pesait 655 ko sur le disque, moteur de recherche WebAssembly, plusieurs paquets d’interface et index compris. Un visiteur ne télécharge que ce dont la page et la requête ont besoin. Par exemple, pagefind-component-ui.js pesait 184 ko et pagefind.js 47 ko avant compression.
Étape 3 : garder publicités, menus et éléments répétés hors de l’index
C’est là qu’un site financé par la publicité doit être un peu attentif. Sans consigne, Pagefind indexe à partir du <body>, si bien que des éléments répétés peuvent se retrouver dans les résultats. La documentation d’indexation fournit deux attributs :
data-pagefind-body, placé sur l’élément de contenu principal, limite l’indexation à cet élément. Dès que cet attribut apparaît sur une page du site, les pages qui ne le portent pas ne sont plus du tout indexées. Le test a affiché exactement cet avertissement.data-pagefind-ignore, placé sur un élément, l’exclut de l’index. Par défaut, il ignore le contenu textuel (index) ;data-pagefind-ignore="all"ignore aussi les filtres, les métadonnées et tout ce qui se trouve à l’intérieur.
Pagefind ignore également automatiquement les éléments nav, footer, script et form.
Pour les emplacements publicitaires, entourez le bloc :
<main data-pagefind-body>
<h1>Sourdough starter</h1>
<p>Feed your starter with flour and water every day.</p>
<div class="ad-slot" data-pagefind-ignore>
<ins class="adsbygoogle" data-ad-client="ca-pub-XXXXXXXXXXXXXXXX" data-ad-slot="1234567890"></ins>
</div>
</main>
Pagefind indexe le HTML statique, pas la page après exécution du JavaScript : les créations publicitaires ne se retrouvent donc jamais dans l’index. Ce qui peut s’y glisser, c’est le texte statique autour de l’emplacement, comme un libellé « Publicité » ou un message de repli. Lors du test, un libellé de substitution placé dans le conteneur ignoré n’apparaissait pas dans le contenu indexé de cette page.
Deux autres fonctions comptent pour les sites de contenu :
- Filtres : ajoutez
data-pagefind-filter="category"à un élément et son texte devient une valeur de filtre. Le test a indexé un filtre de cette façon. - Sites multilingues : Pagefind lit l’attribut
langde chaque page et construit un index distinct par langue.
Construire sa propre page de résultats avec l’API de recherche
Si les composants ne s’accordent pas à votre design, l’API de recherche permet d’interroger l’index depuis votre propre JavaScript :
const pagefind = await import('/pagefind/pagefind.js');
const search = await pagefind.search('starter');
const first = await search.results[0]?.data();
console.log(search.results.length, first?.url, first?.meta.title, first?.excerpt);
La documentation explique la conception : search() ne renvoie que des identifiants de résultats, et l’URL, le titre et l’extrait de chaque résultat se chargent séparément avec data() pour économiser de la bande passante ; ne chargez donc que la première page de résultats. Par défaut, le titre provient du premier h1 de la page, ce qui correspondait à ce que montrait l’index du test. Une page de résultats personnalisée est aussi l’endroit où réserver l’espace d’un éventuel bloc publicitaire affiché à côté des résultats, afin que la liste ne saute pas au chargement de l’annonce.
Pagefind ou AdSense pour la recherche
AdSense pour la recherche affiche des annonces sur les pages de résultats de recherche de votre site via le Programmable Search Engine de Google. Voici la comparaison des deux approches, d’après la page Programmable Search Engine et la présentation de la Custom Search JSON API :
| Pagefind | Programmable Search Engine | |
|---|---|---|
| Coût | gratuit, licence MIT | gratuit (financé par la publicité), option payante sans publicité |
| Revenus | aucun issu de la recherche elle-même | monétisable avec AdSense (AdSense pour la recherche) |
| Origine des résultats | votre HTML généré, indexé à la compilation | index de Google sur votre site |
| Nouvelles pages consultables | après la compilation suivante | après leur exploration par Google |
| Serveur ou API | aucun | hébergé par Google |
| Apparence | votre CSS et vos composants | élément de Google, avec options de style |
Un point à noter si vous prévoyiez une intégration personnalisée : la présentation de Google indique que la Custom Search JSON API est fermée aux nouveaux clients, que les clients existants ont jusqu’au 1er janvier 2027 pour passer à une alternative, et elle suggère Vertex AI Search. Tant qu’elle existe, l’API offre 100 requêtes gratuites par jour, puis coûte 5 $ US pour 1 000 requêtes, dans la limite de 10 000 par jour. L’élément de Programmable Search Engine à intégrer dans une page est un produit distinct.
Comment choisir
- Vous voulez que la page de recherche rapporte de l’argent : Programmable Search Engine avec AdSense pour la recherche. Voir AdSense pour la recherche pour la configuration et les limites.
- Vous voulez une recherche rapide, privée, sans publicité et sous votre contrôle : Pagefind. Vos blocs AdSense habituels s’affichent sur la page de recherche comme sur n’importe quelle autre page.
- Votre site est récent et à peine indexé par Google : Pagefind fonctionne dès le premier jour, puisqu’il ne dépend pas de l’index de Google.
Si votre site est statique et que vous préparez encore la demande d’examen, le guide sur les sites statiques et Jamstack précise ce qui compte pour l’approbation. Un champ de recherche aide la navigation, mais il ne remplace pas des menus clairs et un maillage interne.
Tester le résultat
- Lancez quelques vraies requêtes après chaque compilation et vérifiez que les extraits ne contiennent ni texte de menu, ni texte de bandeau de cookies, ni libellés publicitaires.
- Mesurez la page de recherche avec Lighthouse ; ne chargez l’interface que là où la recherche apparaît.
- Ajoutez la page de recherche à votre audit Playwright pour qu’une modification de gabarit qui casse les composants se voie sur les captures d’écran.
Erreurs fréquentes
- Lancer Pagefind avant la fin de la compilation, ou sur le dossier source au lieu du dossier de sortie.
- Ajouter
data-pagefind-bodyà un seul gabarit : toutes les pages qui n’en ont pas disparaissent silencieusement de la recherche. - Suivre un tutoriel ancien qui utilise le Default UI, puis s’attendre à ce que les options du Component UI s’appliquent.
- Versionner le dossier
/pagefind/généré au lieu de le créer à chaque compilation. - Indexer les pages d’étiquettes et de pagination, qui ajoutent du bruit. Excluez-les en ne mettant
data-pagefind-bodyque sur le vrai contenu.
Outils open source cités
| Outil | Licence |
|---|---|
| Pagefind | MIT |
Questions fréquentes
Pagefind affiche-t-il des publicités dans les résultats de recherche ?
Non. Pagefind est une bibliothèque de recherche qui fonctionne à partir de vos propres fichiers statiques, sans publicité ni monétisation propre. Vos blocs AdSense habituels sur la page de recherche fonctionnent comme sur n'importe quelle autre page, à condition que celle-ci ait un vrai contenu et respecte les règles de placement. Pour afficher des annonces dans les résultats de recherche, c'est le rôle d'AdSense pour la recherche avec Programmable Search Engine.
Pagefind ralentit-il mes pages ?
Seule la page qui affiche l'interface de recherche charge ses scripts, et l'index est découpé en fragments chargés au fil de la saisie. Sur le site de test de trois pages, le script du Component UI pesait environ 184 ko non compressés et le dossier de sortie complet 655 ko, dont la plus grande partie n'est jamais téléchargée par un visiteur. Chargez l'interface uniquement là où la recherche apparaît et testez avec Lighthouse.
Pagefind fonctionne-t-il avec Astro, Hugo ou Eleventy ?
Oui. Pagefind travaille sur n'importe quel dossier de HTML statique, donc après n'importe quel générateur. Il suffit d'ajouter une commande après la compilation, avec --site pointant vers le dossier de sortie, par exemple public pour Hugo ou dist pour Astro. Des paquets d'enrobage existent pour npx et Python, et des binaires précompilés sont disponibles si vous n'avez ni l'un ni l'autre.
Comment empêcher le texte des publicités d'apparaître dans les extraits ?
Entourez les conteneurs publicitaires d'un élément portant data-pagefind-ignore, ou placez data-pagefind-body sur votre contenu principal pour que tout le reste soit ignoré. Pagefind ignore aussi automatiquement les éléments nav, footer, script et form. Lors du test, le texte de remplacement placé dans un conteneur publicitaire ignoré n'apparaissait pas dans le contenu indexé.
Sources
- Pagefind: Static low-bandwidth search at scale · Pagefind
- Getting Started with Pagefind · Pagefind
- Configuring what content is indexed · Pagefind
- Programmable Search Engine: About · Google
- Custom Search JSON API: Overview · Google for Developers
Guides liés
- AdSense pour les recherches : des annonces sur les pages de résultats de votre site avec Programmable Search Engine
Comment AdSense pour les recherches affiche des annonces Search et Shopping sur les résultats de votre site, son lien avec Programmable Search Engine, et l'accès.
- Faire approuver un site statique ou Jamstack par AdSense
Faire approuver un site statique ou Jamstack par AdSense : emplacement du code et d'ads.txt, pièges des sous-domaines de plateforme et des aperçus.
- Lighthouse et Lighthouse CI sur des pages chargées de publicité : configuration, budgets et mesure de l'impact des tiers
Lancez Lighthouse et Lighthouse CI sur des pages AdSense : configuration testée, budgets pour les scripts tiers, comparaison avec et sans annonces.
- Audit automatisé des emplacements publicitaires avec Playwright : captures, nombre de blocs et statut de remplissage
Auditez vos emplacements AdSense avec Playwright sans demander d'annonces : comptez les blocs, vérifiez les hauteurs réservées et ads.txt, capturez le mobile.