✨ 亮点

本次发布引入了语义搜索 Alpha 预览功能、SEO 插件自动 robots.txt 生成、修复 Mermaid C4Context 图表渲染问题，并新增了用于无缝迁移的配置升级命令。

语义搜索（Alpha 预览）

docmd 现在支持基于本地向量嵌入的语义搜索，能够提供超越简单关键词匹配的上下文感知搜索结果。

核心特性：

  • 上下文理解 — 超越精确关键词匹配的上下文感知搜索
  • 自然拼写容错 — 轻松处理拼写错误
  • 发现相关内容 — 即使使用不同术语也能找到相关内容
  • 完全本地处理 — 无需外部服务或 API 调用

通过安装 docmd-search 并在配置中添加 semantic: true 来启用语义搜索：

npm install docmd-search

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

如果未安装 docmd-search，插件会自动降级到关键词搜索，确保文档始终可被搜索。

注意： 此功能为 Alpha 预览版。目前仅提供英语模型，多语言支持计划在未来版本中推出。

我们很高兴介绍 docmd-search。

npm install docmd-search

docmd-search 是专为文档站点打造的语义搜索引擎。它完全在浏览器或 CLI 中运行，无需服务器或 API 密钥，所有处理都在本地完成。

虽然为 docmd 开发，但它也可以集成到其他文档平台、网站和 Web 应用中。

这是早期 Alpha 版本，会继续迭代，但基础架构已经完备。

GitHub： https://github.com/docmd-io/docmd-search
文档： https://docs.docmd.io/search/

SEO 插件：robots.txt 自动生成

SEO 插件现在会在构建过程中自动生成 robots.txt 文件（前提是该文件不存在）。

功能特性：

  • 智能默认值 — 默认包含 User-agent: * 和 Allow: /
  • 站点地图引用 — 设置 config.url 后自动添加站点地图 URL
  • 可选的 AI 爬虫控制
  • 非破坏性 — 已存在的 robots.txt 文件不会被覆盖
{
  "plugins": {
    "seo": {
      "aiBots": false
    }
  }
}

默认情况下允许 AI 爬虫。设置 aiBots: false 会为 GPTBot、ChatGPT-User、Google-Extended、CCBot 等支持的 AI 爬虫添加指令。

Mermaid C4Context 修复

C4Context 图表现在能够正确渲染，不再显示为空白白框。

该问题是由 Mermaid 渲染 C4Context 图表时缺少 SVG 命名空间引起的。docmd 现在会在解析前自动注入所需的命名空间，确保这些图表能够正确渲染。

感谢 @sinsombat 提供的修复和配套测试套件。

配置升级命令

docmd migrate 命令新增了 --upgrade 标志。运行该命令可自动将配置文件就地重写为现代格式。

npx @docmd/core migrate --upgrade

升级会自动处理以下遗留键映射：

遗留键 现代键
projects（顶级） workspace.projects
siteTitle title
siteUrl / baseUrl url
srcDir / source src
outputDir out
defaultLocale i18n.default

原始文件会就地重写。由于迁移是非破坏性的（只重命名键，不修改值），因此不需要备份。

TOC HTML 实体解码

包含特殊字符（如 <、>、& 或弯引号）的标题文本，现在能在目录侧边栏中正确解码显示。此前，包含这些字符的标题会显示原始 HTML 实体（如 &amp;）而非正确字符。

更新日志

新功能：

  1. 新增基于 docmd-search 的语义搜索 Alpha 预览支持。
  2. SEO 插件新增自动 robots.txt 生成功能。
  3. 新增 search.showFilters，用于隐藏搜索结果上方的版本筛选栏。
  4. 新增 search.showConfidence，用于显示语义搜索置信度百分比。
  5. 新增右侧对齐的搜索结果元数据，显示版本和置信度徽章。

缺陷修复：

  1. 修复 Mermaid C4Context 图表渲染为空白白框的问题。
  2. 修复因 workspace 变量在初始化前被访问而导致的实时编辑器模板渲染崩溃。
  3. 修复目录中的 HTML 实体解码问题。
  4. 修复 macOS 上因重复 fs.watch 事件导致的过度开发服务器重载问题。

改进：

  1. 新增 docmd migrate --upgrade，实现配置自动现代化。
  2. 重新设计项目切换器样式，与国际化（i18n）和外观按钮保持视觉一致。
  3. 配置和 navigation.json 的更改现在会触发快速定向重建，而非完全重启。
  4. 开发服务器现已在启动时自动在默认浏览器中打开文档 URL。

感谢 💖

感谢所有贡献者、测试人员和问题报告者帮助改进本次发布。

文档：https://docs.docmd.io/
GitHub：https://github.com/docmd-io/docmd

next 概览