Pular para o conteúdo principal

Configuração de Pesquisa

A documentação utiliza @easyops-cn/docusaurus-search-local para busca local (client-side).

Por que busca local​

  • Roda 100% no browser — sem dependência de serviço externo
  • Funciona com docs privadas atrás de Cloudflare Access — Algolia DocSearch precisaria do crawler bater no site público pra indexar, o que não é possível com Access ligado
  • Sem custo — não tem mensalidade nem cota
  • Suficiente pra docs pequenas — performance ok até centenas de páginas

Como funciona​

O plugin gera um índice estático no momento do build (via docusaurus build). O índice é servido como arquivo JSON e a busca acontece no browser. Lunr.js é o motor por baixo.

Configuração atual​

No docusaurus.config.ts:

plugins: [
  [
    '@easyops-cn/docusaurus-search-local',
    {
      hashed: true,
      language: ['pt', 'en'],
      docsRouteBasePath: '/',
      indexBlog: false,
      highlightSearchTermsOnTargetPage: true,
      explicitSearchResultPath: true,
    },
  ],
],
  • hashed: true — hash no nome do arquivo de índice, cache-friendly
  • language: ['pt', 'en'] — stemming PT-BR + EN
  • docsRouteBasePath: '/' — bate com routeBasePath do preset
  • indexBlog: false — não tem blog
  • highlightSearchTermsOnTargetPage: true — destaca o termo na página de destino

Quando indexa​

A indexação acontece no build. Em npm run start (dev mode) a busca não funciona — só em npm run build + npm run serve, ou em produção depois do deploy.

Quando trocar por algo maior​

Se a doc crescer pra dezenas de seções e/ou o time pedir "busca por significado, não palavra" (ex: pesquisar "ambiente de testes" e achar página sobre "staging"), avalia:

  • Inkeep / Kapa.ai / Mendable — RAG sobre as docs com LLM
  • Trieve — vector search self-hosted, mais barato
  • Algolia Search (não DocSearch) — pago, mas funciona com sites privados se você indexar via API