跳至主内容
版本：稳定版 (v4.x)

Docusaurus 适配器（推荐）

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

如果你使用 Docusaurus，请安装并配置 @docsearch/docusaurus-adapter，即可在当前 Docusaurus 版本上享受最新的 DocSearch 功能。

为什么需要这个适配器​

Docusaurus 提供了出色的内置 Algolia 集成 (@docusaurus/theme-search-algolia)，但 Docusaurus（由 Meta 维护）和 DocSearch 的发布周期并不总是一致的。

该适配器使我们能够快速推出新的 DocSearch 功能（包括 Ask AI 侧边栏支持），而无需用户等待 Docusaurus 集成更新。

实际使用中，这意味着：

  • 更快获得新的 DocSearch 功能

  • 对 Ask AI + 侧边栏功能有更好的兼容性

  • 由 DocSearch 项目维护的专用搜索集成方案

安装​

yarn add @docsearch/docusaurus-adapter
# or
npm install @docsearch/docusaurus-adapter

配置​

保留 @docusaurus/preset-classic，添加适配器插件，并在 themeConfig.docsearch 下配置搜索（推荐方式）：

docusaurus.config.mjs
export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      askAi: {
        assistantId: 'YOUR_ASSISTANT_ID',
        sidePanel: true,
      },
      contextualSearch: true,
    },
  },
};

docsearch 与 algolia 键的对比​

  • themeConfig.docsearch 是规范键名

  • themeConfig.algolia 作为向后兼容的别名被支持

  • 请勿同时定义这两个键

当需要使用 askAi.sidePanel 等较新的 DocSearch 选项时，使用 themeConfig.docsearch 可避免内置 Docusaurus 搜索主题的验证冲突。

自定义搜索界面（SearchBar/SearchPage）​

如需自定义搜索行为或界面，请通过适配器集成路径自定义主题组件（@theme/SearchBar 和 @theme/SearchPage）。

这能让你的自定义实现与 DocSearch 功能更新保持同步，并避免与内置的 Docusaurus Algolia 主题实现产生耦合。