Búsqueda Pagefind en un blog Astro: guía completa, gratis, rápida y con soporte para chino

Cuantos más artículos publico en el blog, más mensajes recibo de lectores: «¿Puedes añadir búsqueda? Recuerdo que escribiste sobre XX, pero no lo encuentro.»

Durante mucho tiempo lo dejé pendiente: Algolia es caro (decenas de dólares al mes para un blog personal) y montar Elasticsearch por tu cuenta es demasiado trabajo. Hasta que descubrí Pagefind: configuración sencilla, índice de solo unas decenas de KB, totalmente gratis y con soporte nativo para chino.

¿Qué es Pagefind? En pocas palabras, un motor de búsqueda diseñado para sitios estáticos. Genera el índice al compilar, la búsqueda ocurre en el navegador, sin servidor backend ni API de terceros. Y lo mejor: es gratis, muy rápido y extremadamente fácil de configurar.

En este artículo te guío paso a paso:

• Por qué Pagefind encaja mejor que Algolia en un blog personal
• Cómo configurarlo en 10 minutos
• Optimización avanzada y ajustes para búsqueda en chino
• Soluciones a problemas frecuentes

Si tienes un blog con Astro y quieres búsqueda sin pagar, este artículo es para ti.

¿Por qué elegir Pagefind?

Antes de añadir búsqueda al blog, comparé las opciones más usadas. Elegí Pagefind por tres razones: costo, privacidad y rendimiento.

Las ventajas de la búsqueda estática

Pagefind es una «búsqueda estática»: el índice se genera al compilar, se despliega con el sitio y la búsqueda ocurre en el navegador. Eso trae varios beneficios claros:

Totalmente gratis. A diferencia de Algolia, que cobra por búsqueda, Pagefind no tiene ningún costo. Por mucho tráfico que tengas, la búsqueda no te costará un centavo.

Respetuoso con la privacidad. Las búsquedas no se envían a servidores de terceros; todas las consultas se resuelven en local. Para lectores que valoran la privacidad, esto importa.

Sin backend. Las soluciones tradicionales requieren servidores, bases de datos y alta disponibilidad. Pagefind es 100 % estático, desplegado en CDN, tan estable como tu sitio.

Carga bajo demanda. El índice se divide en fragmentos y solo se cargan los necesarios cuando el usuario empieza a buscar. La carga inicial no se ve afectada y la experiencia es muy fluida.

Pagefind vs Algolia

Preparé una tabla para comparar rápido:

Algolia es muy potente: velocidad, tolerancia a errores tipográficos y analítica de primer nivel. Pero para un blog personal es matar moscas a cañonazos. Y cuando el tráfico crece, el costo de Algolia se dispara.

Casos reales y datos

El rendimiento de Pagefind es excelente. Según pruebas en BryceWray.com, un sitio de 10 000 páginas genera un índice de menos de 300 KB. La mayoría de blogs rondan los 100 KB.

Los datos oficiales de Pagefind son aún más llamativos: un sitio de 19 páginas indexa en 0,043 segundos. Está escrito en Rust, compila muy rápido y un blog de miles de páginas tarda solo unos segundos.

En la práctica, la documentación oficial de Astro, Starlight, incluye Pagefind como búsqueda por defecto. Si Astro lo eligió, la herramienta es de confianza.

5 pasos para configurar Pagefind

Bien, teoría aparte: vamos a la práctica. Te guío paso a paso; de verdad son solo 10 minutos.

Paso 1: instalar dependencias

Primero instala dos paquetes npm:

npm install astro-pagefind pagefind

¿Por qué dos paquetes?

astro-pagefind es la integración de Astro que ejecuta Pagefind al compilar. pagefind es la librería principal con la UI y la API. Necesitas ambos porque más adelante referenciarás recursos de pagefind directamente.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Paso 2: configurar astro.config.mjs

Abre tu archivo astro.config.mjs y añade la integración de Pagefind:

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

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

¡Así de simple! Con estas líneas, cada vez que ejecutes npm run build, Pagefind indexará automáticamente el contenido de tu sitio.

Paso 3: crear el componente de búsqueda

En src/components/ crea un componente Search.astro:

---
// 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>

Opciones de configuración:

• element: elemento DOM donde se monta la UI de búsqueda
• showSubResults: muestra resultados secundarios (por ejemplo, párrafos coincidentes)
• showImages: muestra miniaturas de página (yo suelo desactivarlo para cargar más rápido)

Si tu sitio usa ViewTransitions, añade la directiva transition:persist para evitar que el componente se reinicialice al cambiar de página:

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

Paso 4: usar el componente de búsqueda

Hay dos formas habituales:

Opción 1: integrarlo en la barra de navegación

Impórtalo en Header.astro o Navbar.astro:

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

<header>
  <nav>
    <!-- tus enlaces de navegación -->
  </nav>
  <Search />
</header>

Opción 2: crear una página de búsqueda independiente

Crea src/pages/search.astro:

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

<Layout title="Búsqueda">
  <main>
    <h1>Buscar artículos</h1>
    <Search />
  </main>
</Layout>

Luego añade un enlace en la navegación hacia /search. Personalmente prefiero esta opción: no satura la barra.

Paso 5: compilar y probar

¡Listo! Ejecuta el build:

npm run build

Si todo va bien, verás una salida similar a:

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

Para probar en local:

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

Abre http://localhost:1234 en el navegador y prueba la búsqueda.

Si ves el cuadro de búsqueda y las consultas devuelven resultados, ¡configuración exitosa!

Configuración avanzada y optimización

Con la configuración básica ya funciona. Si quieres más precisión, velocidad o personalización, puedes ir un paso más allá.

Controlar con precisión el alcance del índice

Por defecto, Pagefind indexa todo el contenido dentro de <body>. Eso incluye navegación, barra lateral y pie de página, lo que distorsiona los resultados.

Por ejemplo, si el pie tiene una sección «Sobre mí», al buscar «autor» coincidirán todas las páginas porque comparten el mismo pie.

La solución es usar data-pagefind-body para definir qué indexar:

<body>
  <nav data-pagefind-ignore>
    <!-- navegación excluida -->
  </nav>

  <main data-pagefind-body>
    <!-- solo el contenido principal -->
    <article>
      <h1>Título del artículo</h1>
      <p>Contenido del artículo...</p>
    </article>
  </main>

  <aside data-pagefind-ignore>
    <!-- barra lateral excluida -->
  </aside>

  <footer data-pagefind-ignore>
    <!-- pie excluido -->
  </footer>
</body>

Con data-pagefind-body, Pagefind solo indexa ese elemento; el resto se ignora. Para excluir elementos puntuales, usa data-pagefind-ignore.

Beneficios:

1. Búsqueda más precisa — solo el contenido principal, sin ruido
2. Índice más pequeño — sin navegación y pie repetidos, el volumen baja un 30 %-50 %

Metadatos y títulos personalizados

Por defecto, Pagefind toma el primer <h1> como título del resultado y los primeros párrafos como resumen. A veces no es suficiente.

Puedes especificarlo con data-pagefind-meta:

<!-- Sobrescribir el título por defecto -->
<h1 data-pagefind-meta="title">Guía de búsqueda en Astro</h1>

<!-- Especificar el resumen -->
<p data-pagefind-meta="description">
  Este artículo explica cómo añadir búsqueda Pagefind a un blog Astro, con pasos completos y optimización para chino.
</p>

<!-- Especificar la imagen -->
<img data-pagefind-meta="image[src]" src="/cover.jpg" alt="Portada">

Ajustar el peso de búsqueda

Si quieres que las coincidencias en títulos aparezcan primero, ajusta el peso:

<h1 data-pagefind-weight="10.0">Título del artículo</h1>
<p data-pagefind-weight="1.0">Contenido del artículo</p>

Cuanto mayor el peso, más arriba aparece el resultado. El valor por defecto es 1,0; los títulos suelen configurarse entre 5,0 y 10,0.

Pruebas de búsqueda en chino

Quizá te preguntes: Pagefind es una herramienta extranjera, ¿cómo maneja el chino?

Buenas noticias: Pagefind incluye soporte multilingüe nativo, chino incluido, sin configuración extra. En pruebas reales funciona bien:

• Segmentación precisa: al buscar «Astro搜索», coincide con «Astro», «搜索» y «Astro搜索功能»
• Coincidencia flexible: al buscar «博客搜索», encuentra «给博客加搜索» y «博客的搜索功能»
• Sin soporte pinyin: la única limitación; buscar «boke» no encuentra «博客» (poco relevante en blogs técnicos)

UI de búsqueda personalizada

La UI por defecto de Pagefind basta para la mayoría. Si quieres personalización profunda (estilos, filtros), usa la API de JavaScript:

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

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

// Ejecutar búsqueda
const search = await pagefind.search("Astro");

// Obtener detalles de resultados
const results = await Promise.all(
  search.results.map(r => r.data())
);

// Renderizar UI personalizada
results.forEach(result => {
  console.log(result.url);      // URL de la página
  console.log(result.meta.title); // Título
  console.log(result.excerpt);   // Resumen
});

La ventaja es control total sobre la UI e integración con tu sistema de diseño. La desventaja: debes escribir la lógica de renderizado. Para la mayoría, la UI por defecto basta.

Problemas frecuentes y soluciones

Durante la configuración pueden surgir pequeños problemas. Aquí van los más comunes y cómo resolverlos.

Problema 1: título o resumen incorrectos en los resultados

Síntoma: el título no es el del artículo o el resumen muestra texto de la navegación.

Causa: Pagefind toma el primer <h1> y los primeros párrafos por defecto; si la estructura no es estándar, elige mal.

Solución: especifica manualmente con data-pagefind-meta:

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

<article>
  <h1 data-pagefind-meta="title">{title}</h1>
  <p data-pagefind-meta="description">{description}</p>
  <!-- resto del contenido -->
</article>

Problema 2: ViewTransitions rompe la búsqueda

Síntoma: con Astro ViewTransitions, al ir a la página de búsqueda el cuadro no funciona.

Causa: ViewTransitions vuelve a ejecutar scripts pero el DOM ya se vació, y la inicialización falla.

Solución: añade transition:persist al contenedor de búsqueda:

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

Esto indica a Astro que conserve el elemento al cambiar de página, sin volver a renderizarlo.

Problema 3: comando pagefind no encontrado al compilar

Síntoma: al ejecutar npm run build aparece: pagefind: command not found

Causa: solo instalaste astro-pagefind, no el paquete principal pagefind.

Solución: instala ambos:

npm install astro-pagefind pagefind

Si persiste, revisa que la integración esté correctamente añadida en astro.config.mjs.

Problema 4: búsqueda devuelve 404 tras el despliegue

Síntoma: funciona en local, pero en Cloudflare Pages/Netlify el navegador devuelve 404 al buscar /pagefind/pagefind.js.

Causa: la carpeta pagefind no está en el artefacto de build; posible error en el comando de compilación.

Solución: asegúrate de que el build incluya la indexación de Pagefind. Con la integración astro-pagefind debería ser automático. Si no, modifica package.json manualmente:

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

Confirma que el despliegue usa este comando de build.

Problema 5: error CSP o índice demasiado grande

Error de CSP (Content Security Policy)

Si la consola muestra Refused to load WebAssembly, es porque Pagefind usa WebAssembly y necesitas añadir wasm-unsafe-eval en el encabezado CSP:

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

En Cloudflare Pages, añádelo en _headers:

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

Índice demasiado grande

Si la carpeta pagefind pesa varios MB tras el build, probablemente indexaste contenido innecesario. Limita el alcance al contenido principal:

<body>
  <nav data-pagefind-ignore>...</nav>
  <main data-pagefind-body>
    <!-- solo esto se indexa -->
  </main>
  <footer data-pagefind-ignore>...</footer>
</body>

Esto reduce el volumen un 30 %-50 %. Además, Pagefind carga bajo demanda: el usuario solo descarga el fragmento que coincide con su consulta.

Casos prácticos y buenas prácticas

Tras la configuración, algunas recomendaciones ayudan a pulir la búsqueda.

Monitorizar la calidad del índice

En cada build, Pagefind muestra estadísticas. Presta atención a:

Running Pagefind...
Indexed 42 pages       ← páginas indexadas
Indexed 3,582 words    ← palabras totales
Created 5 index chunks ← fragmentos del índice
Finished in 0.234 seconds

Interpretación:

• pages debería coincidir con tu número de artículos. Si falta alguno, revisa si quedó excluido por data-pagefind-ignore
• index chunks: cuantos menos, mejor (índice más compacto). Suele haber un chunk cada 1 000-2 000 páginas
• Si el build tarda más de 5 segundos, hay demasiado contenido o el alcance es demasiado amplio

Checklist de despliegue

Antes de producción, verifica:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

1. Confirmar que existe la carpeta pagefind

ls dist/pagefind

Deberías ver pagefind.js, pagefind-ui.js, pagefind-ui.css, etc.

2. Probar la búsqueda

• Busca palabras clave habituales y confirma resultados
• Busca términos en chino y verifica la segmentación
• Busca algo inexistente y confirma el mensaje de «sin resultados»

3. Revisar el tamaño del índice

du -sh dist/pagefind

Normalmente entre 50 KB y 500 KB. Si supera 1 MB, optimiza el alcance.

4. Probar en móvil

Abre el sitio en el teléfono y prueba la búsqueda. La UI por defecto de Pagefind es responsive; una UI personalizada requiere tu propio trabajo.

Consideraciones SEO

La página de búsqueda no necesita indexarse en buscadores. Añade noindex en search.astro:

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

Así los buscadores no indexan la página de búsqueda, pero siguen los enlaces que contenga.

Recomendaciones de rendimiento

1. Carga diferida del componente de búsqueda

Si el cuadro está en la navegación pero pocos usuarios lo usan, carga Pagefind solo al abrirlo:

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

<script>
  // Cargar Pagefind solo al hacer clic en el icono de búsqueda
  document.getElementById('search-icon').addEventListener('click', async () => {
    const pagefind = await import("/pagefind/pagefind-ui.js");
    new PagefindUI({ element: "#search" });
  });
</script>

La primera pantalla no carga recursos de Pagefind y el rendimiento mejora.

2. Aceleración por CDN

Los archivos de índice son estáticos; asegúrate de que el CDN los cachee:

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

3. Optimización de precarga

Si el usuario permanece en la página de búsqueda, puedes precargar índices de palabras frecuentes:

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

// Precargar índices de palabras clave populares
pagefind.preload("Astro");
pagefind.preload("React");

Conclusión

En resumen: Pagefind es la mejor opción para añadir búsqueda a un blog Astro — gratis, fácil de configurar, con buen rendimiento y soporte para chino.

Frente a los cientos de dólares anuales de Algolia, Pagefind ahorra mucho dinero. Sin servidores que mantener ni APIs que configurar: instalas y funciona.

Si aún dudas si añadir búsqueda a tu blog, prueba Pagefind 10 minutos. La configuración es más simple de lo que imaginas y el resultado supera las expectativas.

Si tienes problemas durante la configuración, deja un comentario. Y si ya lo tienes funcionando, comparte tu experiencia.

Lecturas relacionadas:

• Documentación oficial de Pagefind
• Guía de búsqueda de Astro Starlight
• Repositorio GitHub de astro-pagefind