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

Pesquisa

There are a few options you can use to add search to your website:

info

🥇 Docusaurus provides first-class support for Algolia DocSearch.

👥 Other options are maintained by the community: please report bugs to their respective repositories.

🥇 Using Algolia DocSearch

Docusaurus has official support for Algolia DocSearch.

The service is free in most cases: just apply to the DocSearch program.

It works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. Esse conteúdo é consultado diretamente do seu front-end usando a API do Algolia.

If your website is not eligible for the free, hosted version of DocSearch, or if your website sits behind a firewall and is not public, then you can run your own DocSearch crawler.

note

By default, the Docusaurus preset generates a sitemap.xml that the Algolia crawler can use.

Index Configuration

After applying, your site's DocSearch config should be created at:

https://github.com/algolia/docsearch-configs/blob/master/configs/<indexName>.json

This configuration file can be updated by:

caution

It is highly recommended using a config similar to the Docusaurus 2 website config.

Conectando Algolia

Docusaurus' own @docusaurus/preset-classic supports an Algolia DocSearch integration.

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: {
// If Algolia did not provide you any appId, use 'BH4D9OD16A'
appId: 'YOUR_APP_ID',

// Public API key: it is safe to commit it
apiKey: 'YOUR_SEARCH_API_KEY',

indexName: 'YOUR_INDEX_NAME',

// Optional: see doc section below
contextualSearch: true,

// Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them.
externalUrlRegex: 'external\\.com|domain\\.com',

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

caution

The search feature will not work reliably until Algolia crawls your site with the search plugin enabled.

If you are installing the Algolia plugin for the first time and want to ensure the search feature works before deploying it to production, you can ask the DocSearch team to trigger a crawl on a staging environment url or deploy preview.

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.

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

Suporte

The Algolia DocSearch team can help you figure out search problems on your site.

You can contact them by email or on Discord.

Docusaurus also has an #algolia channel on Discord.

👥 Using Typesense DocSearch

Typesense DocSearch works similar to Algolia DocSearch, except that your website is indexed into a Typesense search cluster.

Typesense is an open source instant-search engine that you can either:

Similar to Algolia DocSearch, there are two components:

Read a step-by-step walk-through of how to run typesense-docsearch-scraper here and how to install the Search Bar in your Docusaurus Site here.

You can use a local search plugin for websites where the search index is small and can be downloaded to your users' browsers when they visit your website.

You'll find a list of community-supported local search plugins listed here.

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í.