Como implementar busca interna em um site Astro

Em um site com poucas páginas, o menu basta. Quando o acervo passa de dezenas de textos, o leitor precisa digitar uma palavra e achar o que procura. Em um site estático, gerado como arquivos HTML, isso é um problema: não há banco de dados nem servidor para responder à pergunta.

Este tutorial mostra como resolver isso em um projeto Astro, o framework que gera sites a partir de componentes e arquivos de conteúdo, usando o Pagefind, uma biblioteca de busca para sites estáticos. As instruções seguem a documentação oficial das duas ferramentas, consultada em 08/10/2026. No fim, o texto descreve como a busca do próprio Token & Tech está montada.

Como o Pagefind funciona

O Pagefind não lê o seu código-fonte. Segundo a documentação de início rápido, ele roda depois do gerador do site, lê os arquivos HTML prontos e grava na mesma pasta um pacote estático de busca: o índice e os arquivos da interface.

Três consequências práticas decorrem disso:

• não há servidor de busca. A documentação diz que o Pagefind não tem componente de servidor; a busca fica embutida no site estático e roda no navegador do visitante;
• o índice é dividido em pedaços (chunks). Uma busca baixa só a parte do índice de que precisa, não o índice inteiro;
• funciona com qualquer gerador, porque só depende do HTML final. Astro, Hugo ou páginas escritas à mão são tratados da mesma forma.

Na página inicial do projeto, os autores afirmam que uma busca de texto completo em um site de 10 mil páginas transfere menos de 300 kB pela rede, incluindo a própria biblioteca, e que na maioria dos sites o número fica perto de 100 kB. São números divulgados pelo próprio projeto, sem metodologia publicada na página.

A versão atual, na data desta consulta, é a 1.5.2, de 12/04/2026, segundo a página de versões no GitHub. A 1.5.0, de 06/04/2026, trouxe uma interface nova, baseada em web components, que você verá no passo 2.

Antes de começar

Você precisa de um projeto Astro que gere arquivos estáticos. Pela referência de configuração do Astro, esse é o comportamento padrão: a opção output vale 'static' e o comando astro build grava o resultado em ./dist. Se você mudou o outDir, troque dist pelo seu diretório nos comandos abaixo.

Também precisa de Node.js instalado, já que o Pagefind é distribuído como pacote npm (há ainda instalação via Python, binário pronto ou compilação em Rust, segundo a documentação).

Passo 1: encadear o Pagefind ao build

A documentação de início rápido mostra o comando básico:

npx -y pagefind --site public --serve

A opção --site aponta para a pasta gerada pelo site. O exemplo usa public porque foi escrito para o Hugo; no Astro, a pasta é dist. A opção --serve sobe um servidor de pré-visualização e serve só para testes.

Em produção, a recomendação é rodar o Pagefind depois de cada build, antes da publicação. Em um projeto Astro, o jeito mais simples é instalar o pacote como dependência de desenvolvimento e encadear os comandos no package.json:

npm install --save-dev pagefind

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

A ordem importa. Se o Pagefind rodar antes do astro build, não haverá HTML para indexar. Ao terminar, ele informa quantas páginas e palavras indexou; confira esse resumo no log do build.

Passo 2: criar a interface de busca

O Pagefind gera os arquivos da interface dentro de dist/pagefind/. Eles só existem depois do build, e isso afeta como você os referencia no Astro.

Desde a versão 1.5.0, a interface recomendada é a Component UI, feita de elementos HTML próprios. O guia da Component UI traz este exemplo mínimo, que abre uma janela de busca sobreposta:

---
// src/components/Busca.astro
---
<link href="/pagefind/pagefind-component-ui.css" rel="stylesheet" />
<script is:inline src="/pagefind/pagefind-component-ui.js" type="module"></script>

<pagefind-modal-trigger></pagefind-modal-trigger>
<pagefind-modal></pagefind-modal>

O is:inline tem uma razão. Segundo o guia de scripts do Astro, essa diretiva diz ao Astro para não processar nem empacotar o script, o que é o caso de arquivos servidos como estão, a partir de public/ ou de fora do projeto. O arquivo do Pagefind não existe no momento em que o Astro compila, então ele não deve tentar processá-lo.

Segundo o guia da Component UI, o atalho padrão para abrir a janela é Ctrl+K (Cmd+K no Mac), e Esc fecha. Há outros componentes: <pagefind-searchbox> para uma caixa compacta no menu, e <pagefind-input> com <pagefind-results> para montar uma página de busca dedicada.

A interface anterior, chamada Default UI, continua documentada. Ela usa pagefind-ui.css, pagefind-ui.js e um construtor JavaScript:

<div id="search"></div>
<script is:inline src="/pagefind/pagefind-ui.js"></script>
<script is:inline>
  window.addEventListener("DOMContentLoaded", () => {
    new PagefindUI({ element: "#search", showSubResults: true });
  });
</script>

A documentação da Default UI diz que a Component UI a substitui, mas não marca a antiga como descontinuada nem informa data de fim de suporte. As notas da versão 1.5.0 dizem que ela segue suportada “por enquanto”. Para um projeto novo, a Component UI é o caminho indicado pela documentação; para um projeto existente, a troca pode esperar.

As opções da Default UI estão na referência de configuração da interface. Duas merecem atenção: showImages, que exibe imagem em cada resultado e vem ligada por padrão, e autofocus, que põe o cursor no campo ao carregar e, segundo a própria documentação, pode criar problemas de acessibilidade se usada sem cuidado.

Passo 3: decidir o que entra no índice

Sem configuração, o Pagefind começa a indexar a partir da tag body de cada página. Segundo a página sobre o que é indexado, ele já pula sozinho alguns elementos, como nav, footer, script e form. O resto entra, incluindo cabeçalhos, caixas de inscrição e listas de “leia também” que se repetem em todas as páginas e poluem os resultados. A mesma página descreve os atributos que controlam esse comportamento.

data-pagefind-body marca a área principal da página. Há um efeito que pega muita gente de surpresa: quando pelo menos uma página do site tem esse atributo, as páginas sem ele deixam de ser indexadas. Se você o colocar só no layout de artigos, a página inicial some da busca.

data-pagefind-ignore exclui um elemento e seus filhos do índice. Com o valor padrão, o Pagefind ainda lê metadados e filtros dentro dele. Com data-pagefind-ignore="all", nada é aproveitado daquele trecho.

Em um layout Astro, a combinação típica fica assim (marcar nav e footer é redundante, mas deixa a intenção explícita):

<header data-pagefind-ignore>...</header>
<main data-pagefind-body>
  <nav aria-label="Trilha" data-pagefind-ignore>...</nav>
  <slot />
</main>
<footer data-pagefind-ignore>...</footer>

O título e a imagem de cada resultado também vêm do HTML. Segundo a página de metadados, o Pagefind usa o primeiro h1 como título e a primeira imagem depois dele como miniatura. Você pode sobrescrever com data-pagefind-meta, por exemplo data-pagefind-meta="title" em outro elemento. A mesma página informa que cada chave de metadado guarda um só valor por página e que coincidências no título recebem peso cinco vezes maior na ordenação, por padrão.

Passo 4: separar idiomas

Se o site tem mais de um idioma, o atributo lang da tag html faz o trabalho. Pela documentação de busca multilíngue, o Pagefind lê esse atributo ao indexar e cria um índice por idioma. No navegador, lê o mesmo atributo e carrega o índice correspondente. Uma página em pt-br busca só entre páginas em pt-br.

A mesma página explica dois detalhes:

• o Pagefind aplica stemming, a redução de palavras ao radical, quando há suporte para o idioma; sem suporte, “busca” e “buscar” podem não se encontrar;
• a interface é traduzida para vários idiomas e se adapta ao idioma da página; quando não há tradução, aparece em inglês.

Há uma opção para forçar um único idioma, que desliga esse comportamento e gera um só índice para o site inteiro. Se você já tem rotas por idioma no Astro, como descrito em Como criar um site internacional com Astro, basta garantir que cada layout escreva o lang correto.

Passo 5: filtros, se fizerem sentido

Filtros permitem restringir resultados por categoria, autor ou outro campo. Segundo a página de filtros, você marca o valor no HTML:

<span data-pagefind-filter="categoria">{categoria}</span>
<meta data-pagefind-filter="autor[content]" content={autor} />

A primeira forma usa o texto do elemento; a segunda lê um atributo. O atributo de filtro funciona mesmo fora da área marcada com data-pagefind-body e dentro de trechos ignorados. As chaves any, all, none e not são reservadas.

Filtros só valem a pena se o leitor realmente precisar deles. Em um acervo pequeno, uma caixa de busca simples costuma ser suficiente.

Passo 6: testar

O erro mais comum é testar no lugar errado. A documentação do Pagefind avisa que o servidor de desenvolvimento não mostra a busca, porque o índice só existe depois do build. No Astro, isso significa que astro dev não serve como teste.

O fluxo que funciona:

1. rode npm run build e confira, no log, o número de páginas indexadas;
2. rode astro preview, que, pela referência da linha de comando, serve o conteúdo de dist/ localmente;
3. busque termos que você sabe que existem, termos com acento e termos de páginas que deveriam ficar de fora.

Se uma página esperada não aparece, verifique primeiro o data-pagefind-body. Se aparecem menus nos trechos de resultado, falta data-pagefind-ignore em algum bloco.

E se o site usa Starlight

O Starlight, tema de documentação mantido pela equipe do Astro, já vem com o Pagefind configurado. Pela página de busca do Starlight, basta fazer o build e publicar. Para tirar uma página do índice, use pagefind: false no cabeçalho do arquivo; para tirar só um trecho, data-pagefind-ignore. O tema também aceita trocar o Pagefind pelo Algolia DocSearch, um serviço de busca hospedado, por meio de um plugin oficial.

O caso do Token & Tech

Este site é feito com Astro e usa o Pagefind. A descrição a seguir vem do código do projeto, não de teste de desempenho.

• Build. O script de build roda astro build e, em seguida, pagefind --site dist, antes de uma etapa própria de pós-processamento. O Pagefind está instalado como dependência de desenvolvimento, na versão 1.5.2.
• O que entra. O layout base aplica data-pagefind-body ao main só em páginas marcadas para indexação nos buscadores e que não são a página inicial. Páginas com noindex ficam fora da busca interna pelo mesmo critério.
• O que sai. Cabeçalho, trilha de navegação, bloco de créditos e datas, avisos de revisão, caixa de inscrição e lista de artigos relacionados levam data-pagefind-ignore.
• Idiomas. Cada página declara o idioma no lang da tag html, o que dá um índice separado por idioma.
• Interface. A página de busca usa a Default UI, com resultados por intertítulo (showSubResults), sem imagens e com foco automático no campo. Ela também lê o parâmetro q da URL para abrir já com uma busca preenchida e mostra um aviso para quem está sem JavaScript.

Na avaliação da redação, a migração para a Component UI é uma melhoria possível, não uma urgência, já que a interface atual segue documentada.

Limites que você precisa conhecer

• O índice envelhece. Ele reflete o último build. Conteúdo novo só aparece na busca depois de um novo build e de uma nova publicação.
• Depende de JavaScript. Sem JavaScript, não há busca. Vale exibir um aviso em <noscript> e manter a navegação por categorias funcionando.
• Busca textual, não semântica. O Pagefind encontra palavras. Ele não entende sinônimos nem perguntas em linguagem natural; para isso existem abordagens como a descrita em RAG: como conectar inteligência artificial a documentos, com outros custos e outra infraestrutura.
• Tamanho real. Os números de transferência citados acima são do próprio projeto. Meça no seu site, pela aba de rede do navegador, antes de prometer desempenho a alguém.

O que levar deste texto

O Pagefind encaixa bem no modelo do Astro porque trabalha sobre o resultado final: você gera o site, indexa a pasta dist/ e publica tudo junto. O trabalho que exige atenção não é a instalação, que cabe em uma linha do package.json, mas a curadoria do que entra no índice, com data-pagefind-body, data-pagefind-ignore e o lang correto. Teste sempre sobre um build completo, e lembre que a busca só sabe o que estava no site no momento do último build.