Ajouter Pagefind à un blog Astro : guide complet gratuit, rapide et multilingue

Plus j’écris d’articles, plus je reçois de messages : « Tu peux ajouter une recherche ? Je me souviens que tu as écrit sur XX, mais je ne retrouve plus rien. »

J’ai longtemps repoussé — Algolia coûte trop cher pour un blog perso (des dizaines de dollars par mois), et monter Elasticsearch soi-même, c’est galérer. Puis j’ai découvert Pagefind : configuration simple, index de quelques dizaines de Ko, entièrement gratuit, multilingue natif.

Qu’est-ce que Pagefind ? En bref, un moteur de recherche conçu pour les sites statiques. Il génère l’index au build ; la recherche s’exécute entièrement dans le navigateur — pas de backend, pas d’API tierce. Gratuit, rapide, ultra simple à configurer.

Dans cet article, je vous guide pas à pas :

• Pourquoi Pagefind convient mieux qu’Algolia à un blog personnel
• Comment configurer Pagefind en 10 minutes
• Optimisations avancées et réglage multilingue
• Solutions aux problèmes courants

Si vous avez un blog Astro et voulez la recherche sans payer, cet article est pour vous.

Pourquoi choisir Pagefind ?

Avant d’ajouter la recherche, j’ai comparé les solutions du marché. J’ai choisi Pagefind pour trois raisons : coût, confidentialité et performances.

Les atouts de la recherche statique

Pagefind est une « recherche statique » : l’index est généré au build, déployé avec le site, la recherche s’exécute dans le navigateur.

Entièrement gratuit. Contrairement à Algolia facturé au volume, Pagefind ne coûte rien. Peu importe le trafic, la recherche reste gratuite.

Respectueux de la vie privée. Les requêtes ne partent pas vers un serveur tiers — tout se fait en local. Important pour les lecteurs soucieux de confidentialité.

Sans backend. Les solutions classiques exigent serveur, base de données et haute disponibilité. Pagefind est 100 % statique, sur CDN, aussi stable que vos pages.

Chargement à la demande. L’index est découpé en petits blocs, chargés uniquement quand l’utilisateur cherche. Le premier écran n’en souffre pas — excellente expérience.

Pagefind vs Algolia

Tableau comparatif rapide :

Franchement, Algolia est très puissant — vitesse, tolérance aux fautes, analytics au top. Pour un blog perso, c’est un canon pour tuer une mouche. Et dès que le trafic monte, la facture Algolia grimpe vite.

Cas réels et chiffres

Les performances de Pagefind sont excellentes. D’après BryceWray.com, un site de 10 000 pages produit un index de moins de 300 Ko. La plupart des blogs restent autour de 100 Ko.

Les tests officiels vont plus loin : 19 pages indexées en 0,043 s. Écrit en Rust, le build est ultra rapide — quelques secondes pour des milliers de pages.

En pratique, la doc officielle Astro Starlight intègre Pagefind par défaut. Si Astro l’a choisi, l’outil est fiable.

5 étapes pour configurer Pagefind

La théorie est faite — passons à la pratique. Je vous guide étape par étape ; comptez 10 minutes.

Étape 1 : installer les dépendances

Installez deux paquets npm :

npm install astro-pagefind pagefind

Pourquoi deux paquets ?

astro-pagefind est l’intégration Astro qui lance Pagefind au build. pagefind est la bibliothèque core (UI et API). Les deux sont nécessaires — nous référencerons directement les ressources de pagefind.

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

Étape 2 : configurer astro.config.mjs

Ouvrez astro.config.mjs et ajoutez l’intégration Pagefind :

import { defineConfig } from 'astro/config';
import pagefind from 'astro-pagefind';

export default defineConfig({
  integrations: [pagefind()],
});

C’est tout ! Après ces lignes, chaque npm run build indexera automatiquement votre site.

Étape 3 : créer le composant de recherche

Créez Search.astro dans src/components/ :

---
// src/components/Search.astro
---

<link href="/pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js"></script>
<div id="search"></div>

<script>
  window.addEventListener('DOMContentLoaded', () => {
    new PagefindUI({
      element: "#search",
      showSubResults: true,
      showImages: false
    });
  });
</script>

Quelques options :

• element : élément DOM où monter l’UI
• showSubResults : afficher les sous-résultats (ex. paragraphes correspondants)
• showImages : vignettes de page (je le désactive — chargement plus rapide)

Si vous utilisez ViewTransitions, ajoutez transition:persist pour éviter la réinitialisation à chaque navigation :

<div id="search" transition:persist></div>

Étape 4 : utiliser le composant sur vos pages

Deux approches :

Option 1 : intégrer à la barre de navigation

Dans Header.astro ou Navbar.astro :

---
import Search from '../components/Search.astro';
---

<header>
  <nav>
    <!-- vos liens de navigation -->
  </nav>
  <Search />
</header>

Option 2 : page de recherche dédiée

Créez src/pages/search.astro :

---
import Layout from '../layouts/Layout.astro';
import Search from '../components/Search.astro';
---

<Layout title="Recherche">
  <main>
    <h1>Rechercher des articles</h1>
    <Search />
  </main>
</Layout>

Puis un lien vers /search dans la navigation. Je préfère cette option — la barre reste aérée.

Étape 5 : build et test

Lancez le build :

npm run build

Si tout va bien, vous verrez quelque chose comme :

Running Pagefind...
Indexed 42 pages
Indexed 3,582 words
Created 5 index chunks
Finished in 0.234 seconds

Pour tester en local :

npm run build && npx pagefind --site dist --serve

Ouvrez http://localhost:1234 et testez la recherche.

Si le champ apparaît et que les mots-clés renvoient des résultats — bravo, c’est configuré !

Configuration avancée et optimisations

La recherche fonctionne déjà. Pour plus de précision, de vitesse et d’adéquation à vos besoins, voici des optimisations.

Contrôler précisément la portée d’indexation

Par défaut, Pagefind indexe tout le contenu de <body>. Navigation, sidebar, pied de page — tout entre dans l’index, ce qui fausse les résultats.

Exemple : un pied de page « À propos » sur chaque page fait que « auteur » matche partout.

Solution : l’attribut data-pagefind-body pour cibler la zone à indexer :

<body>
  <nav data-pagefind-ignore>
    <!-- navigation non indexée -->
  </nav>

  <main data-pagefind-body>
    <!-- seul le contenu principal est indexé -->
    <article>
      <h1>Titre de l'article</h1>
      <p>Contenu...</p>
    </article>
  </main>

  <aside data-pagefind-ignore>
    <!-- sidebar non indexée -->
  </aside>

  <footer data-pagefind-ignore>
    <!-- pied de page non indexé -->
  </footer>
</body>

Avec data-pagefind-body, seul ce bloc est indexé. Pour exclure des éléments isolés, utilisez data-pagefind-ignore.

Deux bénéfices :

1. Recherche plus précise — le corps du texte, sans bruit
2. Index plus petit — sans nav/footer répétés, −30 à −50 % de volume

Métadonnées et titres personnalisés

Pagefind prend par défaut le premier <h1> comme titre et les premiers paragraphes comme extrait. Parfois insuffisant.

Utilisez data-pagefind-meta :

<!-- remplacer le titre par défaut -->
<h1 data-pagefind-meta="title">Guide d'intégration de la recherche Astro</h1>

<!-- définir l'extrait -->
<p data-pagefind-meta="description">
  Comment ajouter Pagefind à un blog Astro : étapes complètes et optimisation multilingue.
</p>

<!-- définir l'image -->
<img data-pagefind-meta="image[src]" src="/cover.jpg" alt="Couverture">

Ajuster les poids de recherche

Pour prioriser les correspondances dans les titres :

<h1 data-pagefind-weight="10.0">Titre de l'article</h1>
<p data-pagefind-weight="1.0">Contenu du corps</p>

Plus le poids est élevé, plus le résultat remonte. Défaut : 1,0 ; titres souvent entre 5,0 et 10,0.

Test multilingue

Inquiet du support chinois sur un outil occidental ? Bonne nouvelle : Pagefind gère nativement le multilingue, chinois inclus, sans config.

Résultats concrets :

• Segmentation : « Astro recherche » matche « Astro », « recherche », « fonction recherche Astro »
• Correspondance floue : « recherche blog » matche « ajouter recherche au blog », « recherche du blog »
• Pas de pinyin : « boke » ne trouve pas « 博客 » (peu impactant pour un blog technique)

UI de recherche personnalisée

L’UI par défaut suffit souvent. Pour un contrôle total (styles, filtres), utilisez l’API JavaScript :

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

// initialiser Pagefind
const pagefind = await import("/pagefind/pagefind.js");

// exécuter une recherche
const search = await pagefind.search("Astro");

// récupérer les détails
const results = await Promise.all(
  search.results.map(r => r.data())
);

// rendu UI personnalisé
results.forEach(result => {
  console.log(result.url);      // URL de la page
  console.log(result.meta.title); // titre
  console.log(result.excerpt);   // extrait
});

L’API offre un contrôle total et s’intègre à votre design system. Inconvénient : vous écrivez le rendu — pour la plupart, l’UI par défaut suffit.

Problèmes courants et solutions

Quelques écueils fréquents et leurs correctifs.

Problème 1 : titres ou extraits incorrects

Symptôme : le titre affiché n’est pas celui de l’article, ou l’extrait vient de la navigation.

Cause : Pagefind prend le premier <h1> et les premiers paragraphes — structure de page non standard.

Solution : data-pagefind-meta :

---
// BlogPost.astro
const { title, description } = Astro.props;
---

<article>
  <h1 data-pagefind-meta="title">{title}</h1>
  <p data-pagefind-meta="description">{description}</p>
  <!-- reste du contenu -->
</article>

Problème 2 : ViewTransitions casse la recherche

Symptôme : avec ViewTransitions, en naviguant vers la page de recherche, le champ ne répond plus.

Cause : ViewTransitions réexécute les scripts alors que le DOM a été vidé — échec d’initialisation.

Solution : transition:persist sur le conteneur :

<div id="search" transition:persist></div>

Astro conserve cet élément lors des transitions, sans re-render.

Problème 3 : commande pagefind introuvable au build

Symptôme : npm run build échoue avec pagefind: command not found

Cause : seul astro-pagefind installé, pas le paquet core pagefind.

Solution : installer les deux :

npm install astro-pagefind pagefind

Si ça persiste, vérifiez l’intégration dans astro.config.mjs.

Problème 4 : recherche en 404 après déploiement

Symptôme : OK en local, mais 404 sur /pagefind/pagefind.js après déploiement Cloudflare Pages/Netlify.

Cause : dossier pagefind absent du build — commande de build incorrecte.

Solution : la commande doit inclure l’indexation Pagefind. Avec astro-pagefind, c’est automatique. Sinon, modifiez package.json :

{
  "scripts": {
    "build": "astro build && npx pagefind --site dist"
  }
}

Utilisez cette commande au déploiement.

Problème 5 : erreur CSP ou index trop volumineux

Erreur CSP (Content Security Policy)

Si la console affiche Refused to load WebAssembly, Pagefind utilise WebAssembly — ajoutez wasm-unsafe-eval à la CSP :

Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'

Sur Cloudflare Pages, dans _headers :

/*
  Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'; default-src 'self'

Index trop volumineux

Si le dossier pagefind pèse plusieurs Mo, du contenu superflu est indexé. Limitez la portée au corps :

<body>
  <nav data-pagefind-ignore>...</nav>
  <main data-pagefind-body>
    <!-- seul ce bloc est indexé -->
  </main>
  <footer data-pagefind-ignore>...</footer>
</body>

−30 à −50 % de volume. Pagefind charge à la demande — l’utilisateur ne télécharge que les blocs correspondant à sa requête.

Cas pratiques et bonnes pratiques

Quelques conseils pour peaufiner la recherche après configuration.

Surveiller la qualité d’index

À chaque build, Pagefind affiche des statistiques — surveillez :

Running Pagefind...
Indexed 42 pages       ← pages indexées
Indexed 3,582 words    ← mots total
Created 5 index chunks ← blocs d'index
Finished in 0.234 seconds

Interprétation :

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

• pages doit correspondre au nombre d’articles. Moins ? Vérifiez si data-pagefind-ignore exclut trop
• Moins de index chunks = index plus compact. Environ un chunk par 1 000–2 000 pages
• Build > 5 s : contenu volumineux ou portée trop large — optimisez

Checklist de déploiement

Avant la prod :

1. Vérifier que le dossier pagefind existe

ls dist/pagefind

Vous devez voir pagefind.js, pagefind-ui.js, pagefind-ui.css, etc.

2. Tester la recherche

• Mots-clés courants → résultats OK
• Termes multilingues → segmentation correcte
• Mot inexistant → message « aucun résultat »

3. Vérifier la taille d’index

du -sh dist/pagefind

En général 50 Ko–500 Ko. Au-delà de 1 Mo, réduisez la portée.

4. Test mobile
Sur smartphone, vérifiez le bon fonctionnement. L’UI par défaut est responsive ; une UI custom exige votre propre travail.

Considérations SEO

La page de recherche n’a pas besoin d’être indexée — ajoutez noindex dans search.astro :

<head>
  <meta name="robots" content="noindex, follow">
</head>

Les moteurs n’indexeront pas la page de recherche, mais suivront les liens qu’elle contient.

Optimisations performance

1. Chargement paresseux du composant

Si la recherche est dans la nav mais peu utilisée :

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

<script>
  // charger Pagefind seulement au clic sur l'icône
  document.getElementById('search-icon').addEventListener('click', async () => {
    const pagefind = await import("/pagefind/pagefind-ui.js");
    new PagefindUI({ element: "#search" });
  });
</script>

Le premier écran ne charge pas Pagefind — meilleures performances.

2. Accélération CDN

Les fichiers d’index sont statiques — mettez-les en cache :

# _headers (Cloudflare Pages)
/pagefind/*
  Cache-Control: public, max-age=31536000, immutable

3. Préchargement

Sur une page de recherche, préchargez les mots-clés fréquents :

const pagefind = await import("/pagefind/pagefind.js");

// précharger l'index des mots-clés populaires
pagefind.preload("Astro");
pagefind.preload("React");

Conclusion

En résumé : Pagefind est le meilleur choix pour ajouter la recherche à un blog Astro — gratuit, simple à configurer, performant, multilingue.

Comparé aux centaines de dollars par an chez Algolia, Pagefind fait économiser beaucoup. Pas de serveur, pas d’API : branchez et c’est prêt.

Si vous hésitez encore, essayez Pagefind 10 minutes. C’est plus simple que vous ne le pensez — et le résultat dépasse souvent les attentes.

Des questions en cours de config ? Laissez un commentaire. Déjà Pagefind en place ? Partagez votre retour !

Pour aller plus loin :

• Documentation officielle Pagefind
• Guide recherche Astro Starlight
• Dépôt GitHub astro-pagefind