模板如今就是插件。首个官方模板 Summer 与两个新的可选 UI 功能一同发布 —— Cookie 同意对话框和公告横幅 —— 均直接内置于 @docmd/ui。此外，还包含一项 Docker :latest 修复，让快速启动开箱即用，以及发布后的一系列加固修复（见下文）。

✨ 新增内容

模板如今就是插件

模板包声明 capabilities: ['template']，并附带布局覆盖以及自身的 CSS/JS。新解析器会依次检查四个层级，任一步骤失败即回退到默认：

frontmatter.template  →  config.templates[glob]  →  config.theme.template  →  内置默认

// template-summer/index.js
export default {
  plugin: { name: 'template-summer', version: '0.1.0', capabilities: ['template'] },
  templates: [
    { type: 'layout', templatePath: '...' },
    { type: 'sidebar', templatePath: '...' },
  ],
  templateAssets: [
    { type: 'css', path: '.../summer.css', priority: 10, position: 'head' },
  ],
};

模板可以覆盖 14 个受支持插槽中的任意一个（layout、404、sidebar、header、footer、banner、cookie-consent 等），并可通过 frontmatter 按页面或通过 config 全站设置。用户的 customCss 始终胜出 —— 模板不得使用 !important。

模板 —— 架构与编写指南

☀️ Summer — 首个官方模板

明亮通透的布局，顶部带搜索栏、柔和光晕点缀和更紧凑的卡片网格。

docmd add summer       # 安装并切换您的配置
docmd remove summer    # 还原为默认

内置于默认 UI。默认关闭，需手动开启。

{
  "cookie": {
    "enabled": true,
    "message": "We use cookies to ensure you get the best experience.",
    "policyUrl": "/privacy",
    "position": "bottom-right",
    "expiryDays": 180
  }
}

用户做出选择后会派发 docmd:cookie-consent 事件，插件和模板可据此响应。

📢 全站公告横幅

位于 menubar 之上。支持内联 Markdown 或原始 HTML。

{
  "layout": {
    "banner": {
      "content": "**v0.9 周五发布** —— 阅读公告。",
      "type": "info",
      "link": { "text": "了解更多", "url": "/blog/v0-9" }
    }
  }
}

关闭状态按 session 存储，因此在新访问中横幅会再次出现。

修复

问题 修复
Docker :latest 标签从未发布 工作流现在会在 release 事件上自动打 :latest 标签
Docker 快速启动在空 /docs 时崩溃 Entrypoint 在 /docs 为空时从内置模板种子
Docker 健康检查始终报告异常 现在探测 3000–3005 端口，以匹配 dev server 的自动递增
i18n 字符串在 sidebar/nav partials 中未翻译 t() 函数现已传递给所有布局 partials；在全部 7 个语言中新增 13 个缺失键
复制代码按钮悬浮在代码块上方 按钮现在锚定到外层 wrapper，而非内层
Mermaid 图表在 SPA 导航时失效（整页刷新正常） 插件 <script> 标签现在在每次页面切换时同步到实时 DOM，而不仅仅是初次加载
含有真实链接的 sidebar 分组仅展开而不跳转 点击处理函数现在也匹配真实链接，而不仅仅是 toggle 图标
appearance: "system" 实际不起作用 默认主题 partial 现在读取 DOCMD_APPEARANCE（规范名称），且仅在 localStorage 中存放具体的 light/dark 值时才采纳其覆盖
非英文搜索结果跳到页首而非对应标题 语义搜索客户端现在使用 Unicode 感知的 slug 正则，与 parser 端生成器一致（修复中日韩、西里尔、带变音符号的语言）
Dev server 在无任何编辑时仍每隔几秒全量重建 引入内容签名追踪器，忽略来自 Spotlight/iCloud/Time Machine 的幻影 fs.watch 事件；config 监听器现在改为监听父目录而非文件本身
tag 容器无法接受带引号的 URL 或 external: 前缀 Parser 正则现已支持 "..." 与 '...' 包裹的选项值；url: 为规范属性名，link: 保留为别名

改进

  • 合理的配置默认值 — 一份全新的 docmd.config.json（或不提供任何配置）现在即可开箱运行一个功能完整的站点：页面导航、代码复制按钮、面包屑、搜索、主题切换等均默认开启。完整默认值表 →
  • 插件资源按需加载 — 插件现在可为自身资源声明 condition，使得 JS/CSS 仅在真正需要的页面上加载。在 playground 上验证：Mermaid 约 500 KB 的库现在仅在 3/11 页面加载（之前为 11/11），KaTeX 约 30 KB 的 CSS 仅在 1/1 含数学的页面加载（之前为 11/11）。
  • 更紧凑的 UI — 页头和 menubar 高度从 52px 缩减到 44px；标题锚点图标更小；卡片网格更紧凑。
  • 全新的默认 404 页面 — 玻璃卡片布局配以柔和光晕背景，提供 Return Home / Go Back 操作，完全本地化并支持 RTL。
  • 对比度优化 — 浅色与深色主题下的文本和链接颜色已调整，以满足 WCAG AA。
  • 重新设计的激活态侧边栏链接 — 用"线上的节点"胶囊取代了旧的左边框样式。
  • 键盘焦点现在可见 — :focus-visible 全站获得光晕效果。
  • 步骤永久链接 — docmd steps 列表中每个 <li> 现在都具有全局唯一的 id="step-N"，以及一个在悬停或聚焦时淡入的隐藏 link-2 图标，使单个步骤易于分享和深链。
  • changelog 条目永久链接 — 复用步骤永久链接的模式：每个 changelog 条目的日期现在都具有 id 和一个在悬停时淡入的隐藏 link-2 图标，使单个发布易于分享和深链。
  • --verbose 现已全局生效 — 此前只有 add/remove 识别。现在会在环境中设置 DOCMD_VERBOSE=true，使所有子命令（build、dev、live、init、validate）都能选用详细日志，同时也已转发到 buildSite 与 buildLive 的结构化路径。
  • Docker 镜像零配置即可运行 — docker run ghcr.io/docmd-io/docmd:latest 现在会自动种子一个演示站点；无需挂载卷。
  • 侧边栏导航双击 Bug — 主 UI 脚本在某些服务条件下可能被加载两次，导致点击处理函数触发两次、导航状态卡住。现已防止重复执行。
  • xdg-open 致 dev server 崩溃 — 缺失的浏览器启动二进制不再使 docmd dev 崩溃。
  • @docmd/plugin-search 缺失运行时依赖 — markdown-it 被错误地列为 dev-only；现在首次安装插件即可正常工作。
  • Docker 标签已简化 — 每次发布现在仅发布两个标签：版本号与 :latest。

展望 — v0.9.0 中的 Node 20+

下一个次要版本会将最低版本提升至 Node.js 20+（从 18+），把引擎要求、发布的 Docker 运行时和 CI 环境统一到 Node 22。Node 18 已于 2025 年 4 月 EOL；这能让 docmd 始终运行在有官方支持的运行时上，并留有充足缓冲。

本版本（0.8.7）不受影响 —— >=18 最低版本将保持不变，直到 0.9.0 发布。

现状 (0.8.x) 下一版 (0.9.0)
最低 Node 18+ 20+
Docker 基础 20-alpine 20-alpine
Type Node ^24 ^24
CI 目标 24 24

Skills 更新（docmd-skills@1.1.0）

Skills 已针对 0.8.7 更新为 3 个相互配合的专项 skill。Agent 会根据当前任务和上下文自动选择最相关的 skill，从而减少不必要的 token 消耗，同时保持准确性。

npx docmd-skills [dir]

将 [dir] 替换为您存放 agent skills 的目录 —— 常见选项包括 ~/.claude/skills/、~/.cursor/skills/ 或项目级目录（如 ./.skills/）。

previous Node API 参考 next v0.8.6 - AI 优先与 MCP