Ir para o conteúdo principal
Version: 2.0.0-beta.3

Pesquisa

O próprio Docusaurus @docusaurus/preset-classic suporta uma integração de pesquisa.

Existem duas opções principais, você pode usar o Algolia DocSearch ou introduzir seu próprio componente SearchBar.

Usando o Algolia DocSearch#

O Algolia DocSearch funciona navegando pelo conteúdo do seu site a cada 24 horas e colocando todo o conteúdo em um índice do Algolia. Esse conteúdo é consultado diretamente do seu front-end usando a API do Algolia. Note que seu site precisa estar disponível publicamente para que isso funcione (por exemplo, não atrás de um firewall). O serviço é gratuito.

Se seu site não é elegível para a versão gratuita do DocSearch, ou se o seu site se senta atrás de um firewall, então você pode rodar o seu próprio rastreador Docsearch. Para melhores resultados, você pode usar um arquivo de configuração baseado na configuração do Docusaurus 2..

Conectando Algolia#

Para conectar sua documentação ao Algolia, primeiro adicione o pacote ao seu site:

npm install --save @docusaurus/theme-search-algolia

Em seguida, adicione um campo algolia em seu themeConfig. Solicite ao DocSearch para obter seu índice e chave de API do Algolia.

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    algolia: {      apiKey: 'YOUR_API_KEY',      indexName: 'YOUR_INDEX_NAME',
      // Optional: see doc section below      contextualSearch: true,
      // Optional: see doc section below      appId: 'YOUR_APP_ID',
      // Optional: Algolia search parameters      searchParameters: {},
      //... other Algolia params    },  },};
info

A opção searchParameters usada para ser nomeada algoliaOptions no Docusaurus v1.

Pesquisa contextual#

A busca contextual é principalmente útil para sites versionados do Docusaurus.

Vamos considerar que você tem 2 versões da documentação, v1 e v2. Quando você está navegando pela documentação v2, seria estranho retornar resultados de pesquisa para a documentação v1. Às vezes os documentos v1 e v2 são bastante semelhantes, e você acabaria com resultados de pesquisa duplicados para a mesma consulta (um resultado por versão).

Para resolver esse problema, o recurso de busca contextual entende que você está navegando por uma versão específica dos documentos e criará os filtros de consulta de pesquisa de forma dinâmica.

  • navegando /docs/v1/myDoc, os resultados da pesquisa incluirão apenas os documentos v1 (+ outras páginas sem versão)
  • navegando /docs/v2/myDoc, os resultados da pesquisa incluirão apenas os documentos v2 (+ outras páginas sem versão)
docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    algolia: {      contextualSearch: true,    },  },};
caution

Ao usar contextualSearch: true, os filtros de faceta contextual serão mesclados com os fornecidos com algolia.searchParameters.facetFilters.

ID de aplicativo personalizado#

Quando rodar seu próprio DocSearch crawler será necessário para definir a appId chave de configuração para seu próprio ID do aplicativo. Se não for definido, o appId irá retornar ao usado com a versão gratuita e hospedada do Algolia DocSearch.

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    algolia: {      appId: 'YOUR_APP_ID',    },  },};

Estilizando sua pesquisa no Algolia#

Por padrão, o DocSearch vem com um tema fino que foi projetado para acessibilidade, certificando-se de que as cores e contrastes são padrões de respeito.

Ainda assim, você pode reutilizar as variáveis CSS da Infima do Docusaurus para o estilo DocSearch editando o arquivo /src/css/custom.css.

/src/css/custom.css
html[data-theme='light'] .DocSearch {  /* --docsearch-primary-color: var(--ifm-color-primary); */  /* --docsearch-text-color: var(--ifm-font-color-base); */  --docsearch-muted-color: var(--ifm-color-secondary-darkest);  --docsearch-container-background: rgba(94, 100, 112, 0.7);  /* Modal */  --docsearch-modal-background: var(--ifm-color-secondary-lighter);  /* Search box */  --docsearch-searchbox-background: var(--ifm-color-secondary);  --docsearch-searchbox-focus-background: var(--ifm-color-white);  /* Hit */  --docsearch-hit-color: var(--ifm-font-color-base);  --docsearch-hit-active-color: var(--ifm-color-white);  --docsearch-hit-background: var(--ifm-color-white);  /* Footer */  --docsearch-footer-background: var(--ifm-color-white);}
html[data-theme='dark'] .DocSearch {  --docsearch-text-color: var(--ifm-font-color-base);  --docsearch-muted-color: var(--ifm-color-secondary-darkest);  --docsearch-container-background: rgba(47, 55, 69, 0.7);  /* Modal */  --docsearch-modal-background: var(--ifm-background-color);  /* Search box */  --docsearch-searchbox-background: var(--ifm-background-color);  --docsearch-searchbox-focus-background: var(--ifm-color-black);  /* Hit */  --docsearch-hit-color: var(--ifm-font-color-base);  --docsearch-hit-active-color: var(--ifm-color-white);  --docsearch-hit-background: var(--ifm-color-emphasis-100);  /* Footer */  --docsearch-footer-background: var(--ifm-background-surface-color);  --docsearch-key-gradient: linear-gradient(    -26.5deg,    var(--ifm-color-emphasis-200) 0%,    var(--ifm-color-emphasis-100) 100%  );}

Personalizando o comportamento de busca do Algolia#

Algolia DocSearch suporta uma lista de opções que você pode passar para o campo algolia no arquivo docusaurus.config.js.

docusaurus.config.js
module.exports = {  themeConfig: {    // ...    algolia: {      apiKey: 'YOUR_API_KEY',      indexName: 'YOUR_INDEX_NAME',      // Options...    },  },};

Editando o componente de pesquisa do Algolia#

Se você preferir editar o componente React de pesquisa do Algolia, passe o componente SearchBar em @docusaurus/theme-search-algolia:

npm run swizzle @docusaurus/theme-search-algolia SearchBar

Usando sua própria pesquisa#

Para usar sua própria pesquisa, passe o componente SearchBar em @docusaurus/theme-classic

npm run swizzle @docusaurus/theme-classic SearchBar

Isto criará um arquivo src/themes/SearchBar na pasta do projeto. Reinicie o servidor de desenvolvimento e edite o componente, você verá que o Docusaurus utiliza seu próprio componente SearchBar agora.

Notas: Você pode alternativamente deslizar da barra de pesquisa do Algolia e criar seu próprio componente de pesquisa a partir daí.