第14章 Docusaurus 搜索功能配置指南：Algolia DocSearch 集成与本地搜索选项

版本：2.x 搜索 你有几种方式为网站添加搜索功能： 🥇 Algolia DocSearch（官方） 👥 Typesense DocSearch 👥 本地搜索 👥 自定义 SearchBar 组件 info🥇 Docusaurus 对 Algolia DocSearch 提供一流的支持。 👥 其他选项由社区维护：请向各自的代码仓库报告 Bug。 使用 Algolia DocSearch Docusaurus 官方支持 Algolia DocSearch。 该服务对所有开源项目免费：只需仔细阅读检查清单并申请加入 DocSearch 计划。 DocSearch 每周爬取一次你的网站（日程可在网页界面中配置），并将所有内容聚合到一个 Algolia 索引中。随后，前端直接通过 Algolia API 查询这些内容。 如果你的网站不符合免费托管版 DocSearch 的条件，或者网站位于防火墙后且非公开，那么你可以运行自己的 DocSearch 爬虫。 note默认情况下，Docusaurus preset 会生成 Algolia 爬虫可使用的 sitemap.xml。 从旧版 DocSearch 迁移？ 你可以在我们的博客文章或 DocSearch 迁移文档中阅读更多关于从旧版 DocSearch 基础设施迁移的信息。 索引配置 在你的应用通过审核并部署后，你会收到一封包含所有详情的邮件，用于在项目中添加 DocSearch。你可以通过网页界面编辑和管理爬虫。索引在部署后即刻可用，因此通常无需手动配置。 tip强烈建议使用与 Docusaurus 2 网站配置类似的配置。 连接 Algolia Docusaurus 自带的 @docusaurus/preset-classic 支持 Algolia DocSearch 集成。如果你使用 classic preset，则无需额外安装。 未使用 @docusaurus/preset-classic 时的安装步骤 安装软件包： npmYarnpnpmBunnpm install --save @docusaurus/theme-search-algolia yarn add @docusaurus/theme-search-algolia pnpm add @docusaurus/theme-search-algolia bun add @docusaurus/theme-search-algolia 在 docusaurus.config.js 中注册主题： docusaurus.config.js module.exports = { title: 'My site', // ... themes: ['@docusaurus/theme-search-algolia'], themeConfig: { // ... }, }; 然后，在 themeConfig 中添加 algolia 字段。申请 DocSearch 以获取你的 Algolia 索引和 API 密钥。 docusaurus.config.js module.exports = { // ... themeConfig: { // ... algolia: {
// Algolia 提供的应用 ID
appId: 'YOUR_APP_ID',

// 公开的 API key：可以放心提交
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 返回结果 URL 的部分内容。当多个部署使用不同 baseUrl 但共用同一个搜索索引时很有用。`from` 参数可以使用正则表达式或字符串。例如：localhost:3000 vs myCompany.com/docs
replaceSearchResultPathname: {
from: '/docs/', // 也可以用正则：/\/docs\//
to: '/',
},

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

// 可选：默认开启的搜索页面路径（设为 `false` 可禁用）
searchPagePath: 'search',

// 可选：是否在 Docsearch 上启用 insights 功能（默认为 `false`）
insights: false,

//... 其他 Algolia 参数
},
},
};
info在 Docusaurus v1 中，searchParameters 选项曾叫 algoliaOptions。可能的取值请参考官方 DocSearch 文档。 warning在 Algolia 抓取你的网站之前，搜索功能无法可靠工作。如果网站发生重大改动后搜索失灵，请在 Algolia 控制台触发一次新的抓取。 上下文搜索​ 上下文搜索默认开启。 它确保搜索结果与当前的语言和版本相匹配。 docusaurus.config.jsmodule.exports = {
// ...
themeConfig: {
// ...
algolia: {
contextualSearch: true,
},
},
};
假设你有两个版本的文档（v1 和 v2）以及两种语言（英语和法语）。 在浏览 v2 文档时，返回 v1 文档的搜索结果会很奇怪。由于 v1 和 v2 的文档往往非常相似，同一查询可能会产生重复的搜索结果（每个版本各一条）。 同理，在浏览法语网站时，返回英语文档的搜索结果也不合理。 为解决此问题，上下文搜索功能会识别你正在浏览的特定文档版本和语言，并动态创建搜索结果过滤条件。 * 在 /en/docs/v1/myDoc 上，搜索结果仅包含 v1 文档的英语结果（以及其他未版本化的页面） * 在 /fr/docs/v2/myDoc 上，搜索结果仅包含 v2 文档的法语结果（以及其他未版本化的页面） info 当使用 contextualSearch: true（默认值）时，上下文分面过滤器将与 algolia.searchParameters.facetFilters 中提供的过滤器合并。如有特殊需求，你可以禁用 contextualSearch 并自定义 facetFilters： docusaurus.config.js module.exports = {
// ...
themeConfig: {
// ...
algolia: {
contextualSearch: false,
searchParameters: {
facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
},
},
},
};
参考相关 Algolia 分面文档。 自定义 Algolia 搜索样式 默认情况下，DocSearch 自带一个精细调整的、符合无障碍标准的设计主题，确保颜色和对比度符合规范。 不过，你可以通过编辑 /src/css/custom.css 文件，复用 Docusaurus 的 Infima 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);
/* 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 */
支持 Algolia DocSearch 团队可以帮你解决网站上的搜索问题。你可以通过邮件或 Discord 联系他们，Docusaurus 的 Discord 上也有一个 #algolia 频道。 👥 使用 Typesense DocSearch Typesense DocSearch 的用法与 Algolia DocSearch 类似，区别在于你的网站会被索引到 Typesense 搜索集群中。Typesense 是一个开源的即时搜索引擎，你可以： 自行部署在自己的服务器上，或者 使用托管的 Typesense Cloud 服务。 与 Algolia DocSearch 类似，它也包含两个组件： typesense-docsearch-scraper：爬取你的网站并将数据索引到 Typesense 集群。 docusaurus-theme-search-typesense：可添加到你网站的搜索栏 UI 组件。 这里有一份分步教程，介绍如何运行 typesense-docsearch-scraper，以及如何在 Docusaurus 网站中安装搜索栏。 👥 使用本地搜索 如果搜索索引不大，可以在用户访问网站时直接下载到他们的浏览器里，这时就可以用本地搜索插件。社区支持的本地搜索插件列表见这里。 👥 使用自己的搜索 要使用自己的搜索，需要对 @docusaurus/theme-classic 中的 SearchBar 组件执行 swizzle 操作： npm run swizzle @docusaurus/theme-classic SearchBar yarn swizzle @docusaurus/theme-classic SearchBar pnpm run swizzle @docusaurus/theme-classic SearchBar bun run swizzle @docusaurus/theme-classic SearchBar 这会在项目目录下生成 src/themes/SearchBar 文件。重启开发服务器后编辑该组件，Docusaurus 就会使用你自己的 SearchBar 组件了。 注意：你也可以从 Algolia SearchBar 开始 swizzle，在此基础上创建自己的搜索组件。