跳转至主内容
Version: 2.0.0-beta.5 🚧

搜索

Docusaurus 的 @docusaurus/preset-classic 自带搜索集成。

您有两种方案，一是使用 Algolia DocSearch，二则是使用自己的 SearchBar 组件。

使用 Algolia DocSearch#

Algolia DocSearch 每 24 小时爬取一次您的网站内容，并将其放在 Algolia 索引中。 随后，您的前端调用 Algolia API 来进行查询。 注意，您的网站需要向大众开放才能使用此功能（即不位于防火墙后）。 本服务免费。

If your website is not eligible for the free, hosted version of DocSearch, or if your website sits behind a firewall, then you can run your own DocSearch crawler. For best results, you may want to use a config file based on the Docusaurus 2 config.

连接到 Algolia#

To connect your docs with Algolia, first add the package to your website:

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

Then, add an algolia field in your themeConfig. Apply for DocSearch to get your Algolia index and API key.

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    },  },};
信息

The searchParameters option used to be named algoliaOptions in Docusaurus v1.

上下文搜索#

Contextual search is mostly useful for versioned Docusaurus sites.

Let's consider you have 2 docs versions, v1 and v2. When you are browsing v2 docs, it would be odd to return search results for the v1 documentation. Sometimes v1 and v2 docs are quite similar, and you would end up with duplicate search results for the same query (one result per version).

To solve this problem, the contextual search feature understands that you are browsing a specific docs version, and will create the search query filters dynamically.

  • browsing /docs/v1/myDoc, search results will only include v1 docs (+ other unversioned pages)
  • browsing /docs/v2/myDoc, search results will only include v2 docs (+ other unversioned pages)
docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    algolia: {      contextualSearch: true,    },  },};
caution

When using contextualSearch: true, the contextual facet filters will be merged with the ones provided with algolia.searchParameters.facetFilters.

自定义应用 ID#

When running your own DocSearch crawler, it is required to set the appId configuration key to your own Application ID. If left unset, the appId will fallback to the one used with the free, hosted version of Algolia DocSearch.

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    // 高亮开始    algolia: {      appId: 'YOUR_APP_ID',    },    // 高亮结束  },};

Styling your Algolia search#

By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards.

Still, you can reuse the Infima CSS variables from Docusaurus to style DocSearch by editing the /src/css/custom.css file.

/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%  );}

自定义 Algolia 搜索行为#

Algolia DocSearch supports a list of options that you can pass to the algolia field in the docusaurus.config.js file.

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

编辑 Algolia 搜索组件#

If you prefer to edit the Algolia search React component, swizzle the SearchBar component in @docusaurus/theme-search-algolia:

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

使用您自己的搜索#

To use your own search, swizzle the SearchBar component in @docusaurus/theme-classic

npm run swizzle @docusaurus/theme-classic SearchBar

This will create a src/themes/SearchBar file in your project folder. Restart your dev server and edit the component, you will see that Docusaurus uses your own SearchBar component now.

Notes: You can alternatively swizzle from Algolia SearchBar and create your own search component from there.