@docmd/plugin-search 插件为你的文档提供了强大的客户端搜索体验。它使用 MiniSearch 在构建过程中构建轻量级索引，允许用户在没有服务器端数据库的情况下即时查找技术信息。

配置

在大多数 docmd 模板中，搜索是默认启用的。你可以通过 layout 配置来控制其可见性和位置。

选项 类型 默认值 说明
enabled boolean true 启用或禁用全文搜索索引器。
placeholder string 'Search...' 搜索输入框的自定义占位文本。
maxResults number 10 弹框中显示的最大结果数量。

示例

{
  "layout": {
    "optionsMenu": {
      "position": "header",
      "components": {
        "search": true
      }
    }
  }
}

工作原理

1. 索引（构建时）

在 npx @docmd/core build 过程中，搜索插件会遍历网站上的每一个页面。它会提取标题、副标题和正文文本，然后将这些数据编译成压缩的 search-index.json 文件。

  • 深层链接：索引器会自动将每个标题（#、## 等）注册为可搜索目标。
  • 相关性提升：页面标题被赋予最高权重，其次是副标题，最后是正文内容。

2. 检索（客户端）

当用户打开搜索弹窗（通常通过 / 或 Ctrl+K）时，浏览器会获取 search-index.json 文件。搜索在本地执行，采用模糊匹配（允许轻微的拼写错误）和即时前缀匹配。

自定义搜索行为

虽然搜索插件旨在实现零配置的简洁性，但你可以通过在页面的 frontmatter 中使用 noindex 标志来将特定页面排除在索引之外：

---
title: "内部规范"
noindex: true # 此页面将不会出现在搜索结果或站点地图中
---

技术实现

该插件在网站的 <body> 中注入一个轻量级的搜索弹窗。它完全符合无障碍标准（ARIA 兼容），并支持键盘导航，提供接近原生应用的体验。

搜索分析

如果你启用了 分析插件，读者使用的搜索关键词会被自动捕获并发送到你的分析服务商，让你了解哪些信息缺失或最难找到。

由于搜索完全在客户端进行，没有任何数据（甚至是按键记录）会被发送到服务器。这使得 docmd 成为隐私敏感行业（医疗、金融、安全）文档搜索的黄金标准。

对比

许多文档生成器（如 Docusaurus）依赖于 Algolia DocSearch。虽然 Algolia 功能强大，但它也引入了额外的复杂性：

功能 docmd 搜索 Algolia / 外部方案
设置 零配置（自动化） 复杂（API 密钥、CI/CD 爬取）
隐私 100% 私有（客户端） 数据发送到第三方服务器
离线 支持 不支持
成本 免费 免费层级有限制或付费
速度 即时（内存中） 较快（取决于网络延迟）

语义搜索（Alpha 预览）

认识 docmd-search

我们做了一件令自己颇为自豪的事。

docmd-search 据我们所知，是首个专为文档设计的全离线语义搜索引擎——而且它并不依赖 docmd。它完全在浏览器中运行，无需服务器，无需 API 密钥，用户的任何数据都不会离开本地设备。可接入任何文档引擎、任何静态网站，甚至任意网页，即插即用。

目前处于早期 Alpha 阶段，仍在持续改进中。但核心已经到位——私密、离线、真正智能的搜索。

→ 在 GitHub 上查看

实验性功能 — 语义搜索目前处于 Alpha 预览阶段。默认的关键词搜索仍是生产环境的推荐选项。

语义搜索使用本地向量嵌入来理解查询的含义，可提供超越简单关键词匹配的智能搜索结果。

启用语义搜索

首先，安装 docmd-search 包：

npm install docmd-search

然后在配置中启用它：

{
  "plugins": {
    "search": {
      "semantic": true
    }
  }
}

语义搜索工作原理

与只匹配精确词语的关键词搜索不同，语义搜索能够：

  • 理解上下文 — 搜索"身份验证"可以找到使用"登录"或"注册"等不同表述的相关页面
  • 自然处理拼写错误 — 无需模糊匹配逻辑，模型能理解用户意图
  • 发现相关概念 — 搜索"API"会返回相关的接口文档，而不仅仅是包含"API"字样的页面

配置选项

选项 类型 默认值 说明
semantic boolean false 启用语义搜索（需要安装 docmd-search 包）
showConfidence boolean false 在语义搜索结果中显示相似度匹配置信度徽章
showFilters boolean true 在搜索结果上方显示版本筛选栏（设为 false 可隐藏）
model string 'Xenova/all-MiniLM-L6-v2' 使用的嵌入模型
chunkSize number 512 文本块的最大字符数
chunkOverlap number 50 文本块之间的重叠字符数
indexDir string — 预构建语义索引的路径

对比：语义搜索 vs 关键词搜索

功能 语义搜索 关键词搜索
理解能力 上下文感知 仅精确匹配
拼写容错 强 有限（模糊匹配）
同义词支持 支持 不支持
安装要求 需要 docmd-search 内置，无需安装
索引体积 较大（每 100 个文件约 1-2 MB） 较小
隐私保护 100% 私有（客户端） 100% 私有（客户端）
离线支持 支持 支持

降级机制

如果启用了语义搜索但未安装 docmd-search，插件会自动降级到关键词搜索。这确保无论配置如何，你的文档始终可以被搜索。

Alpha 版本限制

语义搜索仍处于实验阶段，目前存在以下限制：

  • 目前仅支持英语模型（多语言模型可用但测试较少）
  • 不支持增量更新（需要完整重建索引）
  • 内存占用较高（浏览器中约 50-100 MB）
  • 首次加载时可能较慢，因为需要获取嵌入数据

最佳实践

为获得最佳的语义搜索效果：

  1. 排除干扰内容 — 不要将更新日志或草稿内容加入索引：

    {
  "plugins": {
    "search": {
      "semantic": true,
      "exclude": ["**/release-notes/**", "**/drafts/**"]
    }
  }
}

  2. 为 CI/CD 预构建索引 — 使用 indexDir 选项预生成索引：

    npx docmd-search --ui

  3. 监控索引体积 — 定期检查 .docmd-search/ 目录的大小

  4. 充分测试 — 在部署到生产环境前，验证搜索结果的质量

previous 使用插件 next Git