Recherche avec Pagefind : instantanée, statique et entièrement hors-ligne

Comment fonctionne la recherche Pagefind embarquée — modale vs page complète, règles d'indexation, raccourcis clavier, filtrage par locale et personnalisation.

23 avril 2026Tutoriels3min de lecture

Ce site dispose d’une recherche instantanée, totalement statique propulsée par Pagefind. Pas de service tiers, pas de serveur, pas de clé API — Pagefind parcourt le dossier dist/ construit après astro build et écrit un petit index plus un bundle client minuscule dans dist/_pagefind/.

Essayez maintenant : appuyez sur / ou Cmd+K (Ctrl+K sur Windows/Linux) pour ouvrir la modale.

Un bouton vit dans la barre du haut (et sur mobile dans la barre latérale). L’ouvrir charge à la demande /_pagefind/pagefind.js — tant que vous n’ouvrez pas la modale, zéro code de recherche n’est livré.

Points forts :

Champ de saisie auto-focus
Flèches pour naviguer, Entrée pour ouvrir, Échap pour fermer
Liste de résultats avec titre, fil d’Ariane et extrait
Filtrée à la locale courante

Pour le partage profond, la liaison ou la navigation paginée, le thème fournit aussi une recherche pleine page sur /fr/search/ (et /search/). Identique à la modale mais occupant toute la colonne de prose.

bun run build exécute Astro, puis :

pagefind --site dist --output-subdir _pagefind

Pagefind parcourt chaque page .html statique émise par Astro et lit le contenu de l’élément <main> par défaut. Le BaseLayout.astro du thème enveloppe la zone de contenu dans <main id="main">, donc tout fonctionne.

Pour exclure une région de l’index, marquez-la avec data-pagefind-ignore :

<aside data-pagefind-ignore>
  <p>Bandeau marketing — inutile dans les résultats.</p>
</aside>

Le thème exclut déjà la barre latérale, le pied et le panneau de droite pour qu’ils ne polluent pas les résultats avec du texte de navigation.

Si <main> est trop large, marquez le vrai contenu avec data-pagefind-body :

<article data-pagefind-body>
  <!-- seul ceci est indexé -->
</article>

Pagefind supporte aussi les filtres (par tag, catégorie, locale) via data-pagefind-filter :

<article data-pagefind-filter="category:Tutoriels"></article>

L’UI par défaut n’affiche pas de chips de filtre, mais l’API headless les expose — voir « Personnalisation » plus bas.

Touche	Action
`/`	Ouvrir la modale
`Cmd`+`K` / `Ctrl`+`K`	Ouvrir la modale
`↑` / `↓`	Naviguer les résultats
`Entrée`	Ouvrir le résultat
`Échap`	Fermer la modale

Les raccourcis sont câblés dans src/components/islands/SearchButton.astro.

La recherche est consciente de la locale. Le thème lit la locale active depuis l’attribut <html lang> puis contraint la requête Pagefind à l’index de cette locale. Les lecteurs français ne voient pas de hits anglais et vice-versa.

Les chaînes de traduction (placeholder, « pas de résultats », astuces clavier) vivent dans src/i18n/ui.ts sous les clés search.*.

Pagefind est conçu pour les sites statiques. Pour un blog bilingue typique de 50 articles, attendez-vous à :

~50 ko de JS compressé livré au client (uniquement à l’ouverture de la modale)
~150 ko de données d’index compressées, récupérées à la demande et mises en cache
~5–20 ms de latence moyenne par requête (en navigateur, sans aller-retour réseau)

La modale ne charge rien tant qu’on ne clique pas dessus, donc le coût sur la page d’accueil est de zéro.

Ouvrez src/components/islands/SearchButton.astro pour :

Changer le raccourci clavier.
Activer/désactiver l’affichage des images / sous-résultats.
Ajouter une UI de filtres (l’API headless expose pagefind.filters()).
Remplacer le markup de ligne de résultat par votre propre template.

Le composant utilise l’API headless de Pagefind (pagefind.js) — pas le bundle pagefind-ui.js — donc vous avez le contrôle total de la mise en page et du style. Aucun CSS Pagefind supplémentaire n’est livré ; tout est stylé en Tailwind.

Symptôme	Solution
« Search index not available »	Lancez `bun run build` une fois. L’index vit dans `dist/_pagefind/`.
La recherche marche en `preview` mais pas en `dev`	Normal — Pagefind ne tourne qu’après `astro build`.
D’anciens contenus apparaissent encore	Relancez `bun run build`. Ou `bun run pagefind` seul si `dist/` est récent.
Texte de la barre latérale dans les résultats	Vérifiez les attributs `data-pagefind-ignore`.

Commentaires