发布说明 — 0.7.0 : docmd documentation

发布说明
v0.7.0 — i18n 发布

docmd 0.7.0 是一次重大跨越——带来了原生多语言支持（i18n）、内置翻译系统，以及所有核心插件开箱即用的真正零配置默认值。

✨ 亮点

🌍 国际化（i18n）

docmd 现已提供一流的 i18n 支持。配置多个语言区域后，docmd 将为每个语言区域构建完整的本地化站点——包含语言优先 URL（/hi/、/zh/）、翻译后的 UI 字符串和自动语言检测。

每个语言区域独占一个子目录（包括默认语言），让源目录保持整洁，结构一目了然：

docs/
  en/       ← 默认语言区域（渲染至 /）
  hi/       ← 印地语（渲染至 /hi/）
  zh/       ← 中文（渲染至 /zh/）

语言区域 ID、文件夹名称和默认语言完全由你决定——en、hi、fr、de 或你偏好的任意标识符均可使用。

// docmd.config.js
export default {
  i18n: {
    default: 'en',
    locales: [
      { id: 'en', label: 'English' },
      { id: 'hi', label: 'हिन्दी' },
      { id: 'zh', label: '中文' },
    ]
  }
}

此版本还支持跨版本自动生成的各语言区域搜索索引，以及 Search 和 Threads 等官方插件的翻译 UI 组件！

🚀 零配置核心插件

0.7.0 版全面拥抱零配置理念。所有官方核心插件（search、seo、sitemap、analytics、llms、mermaid）现已默认自动启用，无需再手动在 plugins 数组中声明即可使用。

注意： pwa 插件自 0.7.0 起已变更为可选插件。其 Service Worker 的激进缓存策略导致用户在重新构建后看到过期内容。如需离线支持，请使用 docmd add pwa 显式安装。

如需禁用某个核心插件，只需将其标记为 false：

export default {
  plugins: {
    search: false // 禁用自动启用的 search 插件
  }
}

📝 完整更新日志

🌍 i18n 架构

干净的语言区域目录：每个语言区域（包括默认语言）均存放在 src 下独立的子目录中，不再将语言文件夹与内容文件夹混合。
语言优先 URL 生成：构建循环现在会为每个已配置语言区域生成嵌套目录。
逐文件回退：非默认语言区域在翻译缺失时自动继承默认语言区域的页面，并显示自动警告标注。
各语言区域独立导航：每个语言区域目录可拥有自己的 navigation.json，缺失时回退到默认语言区域的导航。
版本控制 + i18n：不含语言区域目录的旧版本仅以默认语言渲染。在任意旧版本中添加语言区域子目录，即可为其启用翻译。
翻译 UI 字符串：原生翻译系统覆盖所有 UI 元素和模板。处理程序解析至 JSON 语言文件（en.json、hi.json、zh.json），所有模板字符串均可通过快速 t('key') 助手访问。
插件 i18n API：插件现支持新增的 translations(localeId) 钩子及客户端字符串的 i18n/ 目录约定。
全局搜索本地化：本地 MiniSearch 索引现按语言区域构建，动态根据上下文渲染版本标记，并优雅提供本地化搜索结果。
零成本回退：未配置 i18n 块的站点构建结果与 0.7.0 之前完全一致——路径和输出均无任何变化。
字符串模式（stringMode: true）：一种专为 noStyle 页面设计的 i18n 模式——从单一源文件生成多语言 HTML。在 HTML 中添加 data-i18n 属性，将翻译文件放置在 assets/i18n/{locale}.json，docmd 即可在构建时克隆渲染输出并进行服务端字符串替换。生成完全翻译的、可被搜索引擎索引的页面，输出至 /{locale}/ 路径。支持 data-i18n（textContent）、data-i18n-html（innerHTML）和 data-i18n-{attr}（属性值）。翻译文件缺失时优雅回退至默认语言。仅适用于 noStyle/HTML 页面——Markdown 文档应使用目录模式。
noStyle 页面客户端 i18n：启用 i18n 配置后，自动注入轻量级 docmd-i18n-strings.js 模块。提供运行时 switchLocale() API、面向 SPA 的 inPlace 模式，以及用于自定义语言切换器的 docmd:i18n-applied 事件。

🔌 插件系统与引擎

核心插件自动激活：零配置默认值自动提供完整的 docmd 套件，无配置开销。
资源生成优化：重构资源流水线，确保静态 CSS、JS 和全局配置仅被构建一次至根目录，无论启用了多少个语言区域或版本。

🎨 界面与容器

容器 icon: 参数：Callout、Card、Collapsible 和 Button 现支持 icon: 参数，可内联渲染 Lucide 图标并与标题对齐。图标已通过 Flexbox 垂直居中并正确缩放。
```
::: card "Setup" icon:rocket
::: button "Get Started" /start icon:arrow-right
```
titleAppend frontmatter 选项：页面现可在 frontmatter 中设置 titleAppend: false，以禁止在 <title> 标签中自动追加"— 网站标题"后缀。适用于主页和落地页。
胶囊样式版本与语言切换器：侧边栏中的版本下拉和语言切换现在渲染为紧凑胶囊按钮，并排在同一行，节省纵向空间。共享 CSS 类确保两个组件尺寸一致。
语言切换器版本感知：浏览无翻译版本的旧版本时，非默认语言区域在语言切换器中显示为不可用（含"N/A"标记），防止导航到不存在的页面。
可翻译的"（最新）"标记：当前版本现在在版本下拉中显示自动生成的、可翻译的"最新"标记，不再在配置标签中硬编码——使用内置翻译系统。
搜索结果版本标记：搜索结果现在在结果标题右侧显示彩色胶囊版本标记。每个版本在构建时获得确定性颜色，便于视觉识别。
响应式语言胶囊：当版本和语言胶囊同时存在时，语言标签在标准侧边栏中自动隐藏，仅显示地球图标；在宽屏模式下展开显示标签。
开发服务器配置热重载：docmd.config.js 的修改现在在 docmd dev 期间触发完整重新构建，无需手动重启。文件监视器在所有平台上均可正确检测配置文件变更。

🐛 问题修复

版本控制 + i18n 冲突：不含语言区域子目录的旧版本目录被错误地复制到所有语言区域。现已修正，仅为默认语言区域渲染——非默认语言区域跳过无翻译的版本。
旧版本中的幽灵语言页面：旧版本目录中的语言区域子目录（如 docs-v1/hi/）在默认语言区域构建时被渲染为常规内容页，产生重复 URL。已通过在扫描时过滤已知语言区域目录名修复。
导航警告误报：即使 navigation.json 存在于语言区域或版本目录中，也会显示"未找到导航设置"消息。现已修复，当任何语言区域或版本目录中存在导航时，不再显示此警告。
自动导航扫描错误目录：启用 i18n 时，自动导航构建器扫描的是源根目录（仅含语言区域目录），导致从文件夹名称生成错误的导航。现已修正为扫描默认语言区域目录。
<title> 标签缺少网站名称：没有显式标题的页面产生空标题标签。模板现在自动使用破折号分隔符追加网站标题（页面 — 网站），主页仅显示网站标题。
旧版本语言切换器 URL 重复：浏览非当前版本时切换语言会产生版本前缀重复的 URL（如 /zh/06/06/page）。已通过在重建语言区域 URL 前剥离版本前缀修复。

🧪 质量保证

0.7.0 通过了涵盖 25 个独立场景、85 项独立断言的完整暴力测试套件——全部通过。每项主要功能均经过单独测试和组合测试：

查看完整测试覆盖

#	场景	断言数
1	零配置（无配置文件）	5
2	零配置 + 嵌套目录	4
3	独立 i18n（非英文默认语言）	5
4	独立版本控制（无 i18n）	5
5	i18n + 版本控制组合	6
6	含部分翻译的旧版本	4
7	语言区域目录缺失（优雅跳过）	3
8	导航解析优先级	2
9	Frontmatter 解析	3
10	容器（callout、tabs、steps、hero）	5
11	代码块（JS、Python）	3
12	自定义 CSS/JS 注入	3
13	编辑链接	3
14	无样式页面	3
15	搜索索引生成	3
16	Sitemap 生成	3
17	EJS 内容页	3
18	README.md 作为 index 回退	4
19	`.markdown` 文件扩展名	3
20	深层嵌套结构（4+ 层）	2
21	零配置自动导航准确性	3
22	标题标签自动追加	2
23	Open Graph 元标签	3
24	重定向	3
25	页面级布局覆盖	3

所有 13 项内部保障检查同样通过。暴力测试脚本包含在 scripts/brute-test.js 中，任何人均可在本地运行。

⚠️ 重大变更

第三方插件简写名称不再解析——如果你正在导入第三方插件，必须使用完整包名。（search、threads 等名称严格保留给 @docmd/plugin-*）。
pnpm onboard 已移除——onboard 脚本已合并到 pnpm prep。使用 pnpm prep 进行完整环境设置，使用 pnpm prep --link（或 pnpm verify --link）同时全局链接 docmd。

迁移指南

运行 npm install docmd@latest 升级。然后：

如果你以默认设置使用核心插件，可以从 plugins 数组中移除它们——它们现已自动启用！
如果你通过简写名称使用第三方插件，请将其更新为完整包名。

完整操作步骤请参阅入门指南 — 安装。