跳到主要内容
版本:Canary 🚧

搜索

有几种为你的网站添加搜索功能的方案:

信息

🥇 Docusaurus 提供对 Algolia DocSearch官方支持

👥 其他选项是社区维护的:请把 bug 报告给他们各自的仓库。

🥇 使用 Algolia DocSearch

Docusaurus 提供对 Algolia DocSearch官方支持

The service is free for any developer documentation or technical blog: just make sure to read the checklist and apply to the DocSearch program.

Docsearch 每周一次爬取你的网站(可以在网页界面上配置具体时间),并将所有内容汇总到一个 Algolia 索引中。 随后,你的前端会调用 Algolia API 来直接查询这些内容。

如果你的网站不符合免费托管的 DocSearch 版本的要求, 或者如果你的网站位于防火墙后且不公开,那么你可以运行你自己的 DocSearch 爬虫。

备注

Docusaurus 预设会默认生成一份 sitemap.xml 供 Algolia 爬虫使用。

从旧 DocSearch 迁移来的?

要了解更多关于从旧 DocSearch 架构迁移到新架构的内容,你可以读读我们的博客文章或者 DocSearch 迁移文档

配置索引

在你的申请被批准并部署完毕后,你会收到一封包含所有详细信息的电子邮件,告诉你如何将 DocSearch 添加到你的项目。 可以通过网页界面来编辑和管理你的网站爬取。 部署完毕后,索引就立即可用了,所以一般不需要手动配置。

提示

我们强烈建议让你的配置接近于 Docusaurus v3 网站的配置

连接到 Algolia

Docusaurus 的 @docusaurus/preset-classic 自带 Algolia DocSearch 集成。 如果你用的是经典预设,就不需要额外安装任何东西。

不使用 @docusaurus/preset-classic 时的安装步骤
  1. 安装软件包:
npm install --save @docusaurus/theme-search-algolia
  1. docusaurus.config.js 中注册主题:
docusaurus.config.js
export default {
title: 'My site',
// ...
themes: ['@docusaurus/theme-search-algolia'],
themeConfig: {
// ...
},
};

然后,在你的 themeConfig 中添加一个 algolia 字段。 要取得你的 Algolia 索引名和 API 密钥,请**向 DocSearch 申请**。

docusaurus.config.js
export default {
// ...
themeConfig: {
// ...
algolia: {
// Algolia 提供的应用 ID
appId: 'YOUR_APP_ID',

// 公开 API 密钥:提交它没有危险
apiKey: 'YOUR_SEARCH_API_KEY',

indexName: 'YOUR_INDEX_NAME',

// 可选:见下文
contextualSearch: true,

// 可选:声明哪些域名需要用 window.location 型的导航而不是 history.push。 适用于 Algolia 配置会爬取多个文档站点,而我们想要用 window.location.href 在它们之间跳转时。
externalUrlRegex: 'external\\.com|domain\\.com',

// 可选: 替换Algolia的部分网址。 Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs
replaceSearchResultPathname: {
from: '/docs/', // or as RegExp: /\/docs\//
to: '/',
},

// 可选: Algolia 搜索参数
searchParameters: {},

// 可选: 搜索页面的路径,默认启用(可用`false`禁用)
searchPagePath: 'search',

//... 其它 Algolia 搜索参数
},
},
};
信息

searchParameters 选项即 Docusaurus v1 中的 algoliaOptions

请参阅 DocSearch 官方文档了解可取的值。

warning

在 Algolia 爬取你的网站之前,搜索功能无法可靠地工作。

如果在任何重大更改之后,搜索无法正常工作,请用 Algolia 控制面板触发一次新爬取

上下文搜索默认启用

它确保搜索结果与当前语言和版本相关。

docusaurus.config.js
export default {
// ...
themeConfig: {
// ...
algolia: {
contextualSearch: true,
},
},
};

假设你有两个文档版本(v1v2)以及两种语言(enzh-Hans)。

浏览 v2 的文档时,返回 v1 文档的搜索结果会很奇怪。 有时侯 v1 和 v2 的文档非常相似,导致同一个查询产生重复的搜索结果(每个版本一个结果)。

同样,在浏览中文网站时,返回英文文档的搜索结果也很奇怪。

上下文搜索功能解决了这个问题。它能够理解你正在浏览某个文档版本及语言,并动态创建搜索过滤器。

  • /en/docs/v1/myDoc 上,搜索结果将只包含英文 v1 文档的结果(以及其他未分版本的页面)
  • /zh-Hans/docs/v2/myDoc 上,搜索结果将只包含** 中文** v2 文档的结果(以及其他未分版本的页面)
信息

使用 contextualSearch: true(默认开启)时,上下文约束面过滤器 (contextual facet filters) 会和 algolia.searchParameters.facetFilters 合并。

如果有特别需求,你可以禁用 contextualSearch 并自定义 facetFilters

docusaurus.config.js
export default {
// ...
themeConfig: {
// ...
algolia: {
contextualSearch: false,
searchParameters: {
facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
},
},
},
};

请参阅相关的 Algolia 约束面文档

DocSearch 默认自带一个精心设计的主题,保证可访问性,确保颜色和对比度符合标准。

你仍然可以复用 Docusaurus 的 Infima CSS 变量,通过编辑 /src/css/custom.css 文件给 DocSearch 提供样式。

/src/css/custom.css
[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);
/* 弹窗 */
--docsearch-modal-background: var(--ifm-color-secondary-lighter);
/* 搜索框 */
--docsearch-searchbox-background: var(--ifm-color-secondary);
--docsearch-searchbox-focus-background: var(--ifm-color-white);
/* 条目 */
--docsearch-hit-color: var(--ifm-font-color-base);
--docsearch-hit-active-color: var(--ifm-color-white);
--docsearch-hit-background: var(--ifm-color-white);
/* 页脚 */
--docsearch-footer-background: var(--ifm-color-white);
}

[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);
/* 弹窗 */
--docsearch-modal-background: var(--ifm-background-color);
/* 搜索框 */
--docsearch-searchbox-background: var(--ifm-background-color);
--docsearch-searchbox-focus-background: var(--ifm-color-black);
/* 条目 */
--docsearch-hit-color: var(--ifm-font-color-base);
--docsearch-hit-active-color: var(--ifm-color-white);
--docsearch-hit-background: var(--ifm-color-emphasis-100);
/* 页脚 */
--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 支持一系列选项。你可以通过 docusaurus.config.jsalgolia 字段传递它们。

docusaurus.config.js
export default {
themeConfig: {
// ...
algolia: {
apiKey: 'YOUR_API_KEY',
indexName: 'YOUR_INDEX_NAME',
// 选项……
},
},
};

编辑 Algolia 搜索组件

如果你想要编辑 Algolia 搜索的 React 组件,可以 swizzle @docusaurus/theme-search-algoliaSearchBar 组件:

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

支持

Algolia DocSearch 团队可以帮助你解决网站的搜索问题。

You can reach out to Algolia via their support page or on Discord.

Docusaurus 在 Discord 上也有一个 #algolia 频道。

👥 使用 Typesense DocSearch

Typesense DocSearch 类似于 Algolia DocSearch,只不过你的网站会被 Typesense 搜索集群索引。

Typesense 是一个开源的即时搜索引擎。你可以:

与 Algolia DocSearch 类似,Typesense 分为两个部分:

关于如何运行 typesense-docsearch-scraper,这里有一个分步教学的指南。这里是如何在你的 Docusaurus 网站上安装搜索栏的教程。

对于搜索索引比较小的网站,你可以使用本地搜索插件。索引会在用户访问你的网站时下载到浏览器中。

这里列出了一些社区维护的本地搜索插件

要使用你自己的搜索,请 swizzle @docusaurus/theme-classic 中的 SearchBar 组件。

npm run swizzle @docusaurus/theme-classic SearchBar

This will create an src/theme/SearchBar file in your project folder. 重启你的开发服务器,编辑组件,你会看到 Docusaurus 开始使用你自己的 SearchBar 组件了。

备注:你也可以 swizzle Algolia 的 SearchBar,并以这个组件为基础,创建你自己的搜索组件。