跳到主要内容
版本:2.1.0

搜索

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

信息

🥇 Docusaurus 提供对 Algolia DocSearch官方支持

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

🥇 使用 Algolia DocSearch

Docusaurus 提供对 Algolia DocSearch官方支持

此服务对开源项目是免费的:你只需要阅读检查清单,然后向 DocSearch 项目申请即可。

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

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

备注

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

从旧 DocSearch 迁移来的?

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

配置索引

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

提示

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

连接到 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
module.exports = {
title: 'My site',
// ...
themes: ['@docusaurus/theme-search-algolia'],
themeConfig: {
// ...
},
};

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

docusaurus.config.js
module.exports = {
// ...
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 搜索参数
searchParameters: {},

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

// ……其他 Algolia 参数
},
},
};
信息

searchParameters 选项即 Docusaurus v1 中的 algoliaOptions

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

注意

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

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

上下文搜索默认启用

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

docusaurus.config.js
module.exports = {
// ...
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
module.exports = {
// ...
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
module.exports = {
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 团队可以帮助你解决网站的搜索问题。

你可以通过 emailDiscord 联系他们。

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

这会在你的项目文件夹中创建 src/themes/SearchBar 文件。 重启你的开发服务器,编辑组件,你会看到 Docusaurus 开始使用你自己的 SearchBar 组件了。

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