Releases

Release v3.0.0

Released on October 27, 2026

!WARNING@movk/nuxt-docs 3.0 是一个破坏性版本。

默认关闭的功能(组件文档、AI Chat、Mermaid、无障碍检查、国际化)改为 optional peer 依赖,文档固定位于 content/docs/,部分配置字段重命名,并以编辑式排版作为新的视觉默认值。缺少依赖或配置冲突会在构建期直接报错并给出原因。

完整变更说明见 从 v2 迁移(English),本页底部附 3.0.0 的完整 changelog。

亮点

  • 按需依赖:Layer 直接依赖由 47 个降至 35 个,启用功能而未安装依赖时构建期报错并给出安装命令
  • 功能开关:movkNuxtDocs.componentDocs / mcp / ogImage / mermaid / a11y 与 aiChat.enabled 统一解析,关闭的功能不参与打包与类型检查
  • 编辑式默认外观:paper / vermilion 配色、衬线标题、报头式页头、编号侧栏与目录,支持 theme.font: 'sans' 改回无衬线
  • 导航即配置:header.nav / docs.categories 在 app.config.ts 中声明,文案可按语言区分
  • 落地页组件:LandingCover、LandingIndex、LandingSection 等提升到 Layer
  • 面向 AI 代理:基于 nuxt-agent-discovery 的 Markdown 内容协商、/sitemap.md、MCP 服务卡片与 Agent Skills;MCP 工具支持 locale 参数
  • 国际化:站点 i18n/locales/{code}.json 与内置翻译合并,可新增语言或覆盖文案
  • 文档重写:开始 / 指南 / AI / 写作 / 组件 / 参考六区,中英文同步,v2 旧路径 301 跳转

用 AI 迁移

把下面的提示词交给 Claude Code、Cursor、Codex 等编码代理,它会按迁移指南检查并修改你的项目。代理也可以直接读取迁移指南的 Markdown 版本:https://docs.mhaibaraai.cn/raw/docs/getting-started/migration.md。

点击展开完整迁移提示词
你正在把**当前项目**(@movk/nuxt-docs 的使用方)升级到 **@movk/nuxt-docs 3.0**。

v3 把默认关闭的功能改为 optional peer 依赖,固定了内容目录,重命名了部分配置字段,并以编辑式排版作为新的视觉默认值。大多数变更在构建期直接报错,少数(视觉默认值、组件覆盖)只会改变外观。

你的任务:

1. 只在**当前仓库**中查找受下列变更影响的代码、配置与内容。
2. 按清单改为 v3 写法,不要为旧写法添加兼容层。
3. 保持站点现有行为与外观;第 6 节的视觉默认值先询问我是否保留 v2 外观,再决定是否改回。
4. 完成后运行项目的 `nuxt build`、类型检查与测试,修复由迁移引起的失败。
5. 最后列出:修改的文件、新安装的依赖、需要我人工确认的项。

## 不要改动

- `extends: ['@movk/nuxt-docs']` 写法不变
- 覆盖 `useHeader` / `useCategory` 的旧写法仍然可用;只在我同意时才改为 `app.config` 的 `header.nav` / `docs.categories`
- MDC 语法、frontmatter 字段、文件名数字前缀不变
- `AI_API_KEY`、`AI_BASE_URL`、`NUXT_GITHUB_TOKEN` 环境变量名不变

## 前置

先将 `@movk/nuxt-docs` 升级到 `^3.0.0`,用项目实际使用的包管理器:

```bash
pnpm add @movk/nuxt-docs@^3.0.0
```

## 变更清单

### 1. 可选功能的依赖

以下功能的依赖不再随 Layer 安装。只为项目实际启用的功能安装:

| 功能 | 启用条件 | 需安装 |
|---|---|---|
| 组件文档 | 页面中使用 `ComponentProps` / `ComponentSlots` / `ComponentEmits` / `ComponentCode` / `ComponentExample` | `nuxt-component-meta vue-component-meta prettier`,并设置 `movkNuxtDocs.componentDocs: true` |
| AI Chat | 构建期存在 `AI_API_KEY` 或 `aiChat.enabled: true` | `ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes` |
| Mermaid | `movkNuxtDocs.mermaid` 开启 | `mermaid dompurify`(v2 缺依赖时静默跳过,v3 构建报错) |
| 无障碍检查 | v2 默认开启,v3 默认关闭 | 需要时设置 `movkNuxtDocs.a11y: true` 并安装 `@nuxt/a11y` |
| 国际化 | `modules` 中含 `@nuxtjs/i18n` | `@nuxtjs/i18n` |

判断组件文档是否启用:在 `content/` 与 `app/` 中搜索上表的组件名。

### 2. AI Chat 与 MCP

启用 AI Chat 时不能设置 `movkNuxtDocs.mcp: false`,否则构建报错。如两者同时出现,删除 `mcp: false`。

### 3. 内容目录

文档必须位于 `content/docs/`,其他语言位于 `content/{locale}/docs/`,路由前缀固定为 `/docs`。如果文档直接放在 `content/` 下(如 `content/1.getting-started/`),整体移入 `content/docs/`,并更新站内链接、`header.nav`、`docs.categories` 等处的路径。`content/index.md`、`content/releases.*`、`content/templates.*` 保持在 `content/` 根目录。

### 4. 配置字段

- `app.config.ts` 中 `github.per_page` 重命名为 `github.perPage`
- v2 默认只显示 `2025-01-31` 之后、构建时刻之前的提交,v3 不再过滤。原来依赖该行为时显式设置 `github.since` / `github.until`

### 5. 移除的作者私有默认值

v3 不再携带以下默认值。如果站点依赖它们,在项目配置中显式设置:

- `header.avatar`(v2 指向作者头像)
- `github.dateFormat.options.timeZone: 'Asia/Shanghai'`
- Alibaba PuHuiTi 字体 CDN:字体栈仍优先使用该字体,需要时通过 `app.head.link` 自行引入样式表

### 6. 视觉默认值(先询问我)

| 项 | v2 | v3 | 改回 v2 |
|---|---|---|---|
| 主色 / 中性色 | `green` / `slate` | `vermilion` / `paper` | `app.config.ts` 设置 `ui.colors.primary: 'green'`、`ui.colors.neutral: 'slate'` |
| 标题字体 | 无衬线 | 衬线(Fraunces) | `theme.font: 'sans'` |
| 代码高亮 | Nuxt Content 默认 | `github-light` / `github-dark` | `nuxt.config.ts` 设置 `content.build.markdown.highlight.theme` |

项目已显式配置的颜色、字体、高亮主题保持不变。

### 7. 组件覆盖

在 `app/components/` 中查找与 Layer 同名的覆盖组件:

- 可覆盖的组件、挂载位置与 props 以文档「自定义」页的覆盖契约表为准,未列出的(如 `ThemePickerButton`)属于内部实现,提示我需要人工确认
- 页头、侧栏、目录、上下篇、页脚结构已重做;覆盖过这些组件或在 CSS 中依赖其 DOM 结构的,标记出来交给我确认
- `PageHeaderLinks` 的挂载位置改到文档页导语下方的元信息行
- Layer 覆盖了 Nuxt UI 的 `ProsePre`;项目自己的 `ProsePre` 覆盖仍然优先,无需改动

### 8. 删除的 API

- 删除 `HeroBackground` 组件的所有引用,以及 `definePageMeta({ heroBackground: ... })` 中的 `heroBackground`
- 在项目中覆盖 `useToolCall` 时,`state` 参数类型由 `ToolState` 改为 `string`,并删除不再使用的 `ToolState` 导入

## 验证

1. 运行 `nuxt build`。出现「已启用的功能缺少依赖」时按提示安装;出现 `[request error]` 日志说明有死链,修正对应链接
2. 运行项目的类型检查与测试
3. 启动开发服务器,抽查首页、一篇文档页与使用组件文档的页面

3.0.0 (2026-10-27)

⚠ BREAKING CHANGES

  • componentDocs 默认关闭,使用 ComponentProps / ComponentSlots / ComponentEmits / ComponentCode / ComponentExample 需设置 movkNuxtDocs.componentDocs: true;@nuxt/a11y 默认关闭
  • github: github.per_page 重命名为 github.perPage;不再默认过滤 2025-01-31 之前及构建之后的提交
  • layer 不再加载 Alibaba PuHuiTi 字体 CDN,不再默认 Asia/Shanghai 时区与头像
  • deps: 启用 AI Chat、组件文档、a11y 时需自行安装对应依赖
  • 文档必须放在 content/docs(其余语言为 content/{locale}/docs)
  • theme: 移除 HeroBackground 组件与 heroBackground page meta;默认主色由 green 改为 vermilion,neutral 由 slate 改为 paper;PageHeaderLinks 挂载位置改为导语下方的元信息行

✨ Features

  • aside: 侧栏当前项指示条随路由平滑滑动 (06fe2a7)
  • content: 包管理器与 TS/JS 代码组全站同步 (3c1f62b)
  • docs: frontmatter 新增 requires 与 difficulty 页面元信息 (55c8101)
  • docs: 文档站引入 Noto Serif SC 并改用文字字标 (c8ccf14)
  • docs: 新增 A–Z 索引页 (e2d69b0)
  • docs: 新增截图脚本并重新生成文档配图 (75960a2)
  • docs: 由 nuxt.schema.ts 自动生成 app.config 配置参考 (4122e63)
  • docs: 落地页改为编辑式排版 (7d50c16)
  • docs: 落地页配图支持亮暗两张截图 (b04e0af)
  • header: 文档页页头底线叠加阅读进度 (4113c6d)
  • header: 语言切换器改用图标与语言代码 (df41067)
  • i18n: 支持站点 i18n/locales 翻译文件 (529faea)
  • landing: 落地页组件提升为 layer 内容组件 (cc61fdb)
  • mcp: 工具与提示词支持 locale 参数 (43d02c7)
  • nav: 页头导航与侧边栏分类改由 app.config 声明 (72b6132)
  • og-image: 默认 OG 图片改为 paper / vermilion 编辑风 (2159ef8)
  • prose: 代码块复制按钮显示文字反馈 (103227d)
  • search: ⌘K 面板新增最近访问 (c344ac2)
  • templates: 三套模板改为中性起步内容 (044d830)
  • templates: 案例展示页改为编辑式排版 (71b17d1)
  • theme: 文档外壳改为编辑风视觉 (e3b5310)
  • 可选功能改为显式开关并按需加载 (da0d9f1)
  • 启用 View Transitions 页面切换 (3ab1ea7)

🐛 Bug Fixes

  • ai-chat: 代码高亮主题与正文统一为 github-light / github-dark (825c606)
  • dev: 修复依赖扫描因 @nuxtjs/i18n 的 #components 解析失败而跳过预构建 (90cf4e1)
  • git: GitHub Actions 的 PR 构建使用源分支生成提交历史链接 (8dcfb06)
  • i18n: 页头与主题面板的固定英文文案改为内置翻译 (d1aeedd)
  • mcp: examples 资源未 await 导致返回空对象 (d44c90c)
  • mcp: search-composables 匹配嵌套目录下的组合式函数页面 (7b04054)
  • mdc: 纯文本提示块在 raw markdown 中与下一行标题粘连 (26854be)
  • navigation: 未声明分类的页面回退到概览,栏目链接指向首篇 (a4b9f99)
  • prose: 合并 ProsePre 覆盖并注册为全局组件 (96f9a40)
  • prose: 表格单元格增加左右内边距 (26ae53b)
  • templates: 移除落地页中已删除的 hero-background (159f382)
  • theme: 接通 theme 配置并以站点配置为重置基准 (95a8ce2)
  • theme: 暗色模式下反色文字改为墨色 (ee4ec99)

⚡ Performance Improvements

  • Markdown 解析缓存改为容量 200 的 LRU (d9d42b5)

📝 Documentation

  • agents: 精简 AGENTS.md 并修正过时的模块与路由描述 (9e3df81)
  • agents: 补充功能开关、可选依赖与类型隔离约定 (f103e5f)
  • agents: 补充测试命令、CI 结构与 i18n 注意事项 (8373922)
  • ai: 重写 AI 区并新增代理发现页 (10e57f5)
  • composables: 参考页 slug 与函数名保持一致 (c471054)
  • getting-started: 重写开始区并新增 v2 迁移指南 (0d9c25f)
  • guide: 重写国际化、部署、故障排查并新增 OG 图片与常见问题 (7f00162)
  • guide: 重写配置总览与定制页并新增主题、导航、功能开关 (c7346d2)
  • i18n: 更正 locales 声明 file 的说明以匹配站点翻译 (814b4b0)
  • llms: llms.txt 按文档分区列出页面并改用英文描述 (2ca0552)
  • migration: 新增用 AI 迁移的完整提示词 (05071b8)
  • README 列全三套模板并注明模板不含 AI 依赖 (55e642a)
  • reference: 重写组合式函数参考并补全未文档化的函数 (979e239)
  • skills: 按 v3 约定重写 create-docs 与 review-docs (da780b3)
  • templates: 完善案例描述并新增提交站点入口 (2f8efc0)
  • writing: 重写写作区与组件区并新增内容组件页 (a8cdd7d)
  • 以 v3.0.0 版本号重新生成文档截图 (1911969)
  • 新增可覆盖组件契约表并说明 MCP 的 locale 参数 (9def064)
  • 覆盖契约表更新 PageHeaderLinks 挂载位置 (167bc30)

♻️ Code Refactoring

  • component-docs: ComponentCode 与 raw markdown 共用代码片段生成 (7192fcc)
  • component-docs: ComponentExampleExtras 改为最低优先级兜底注册 (a21bc23)
  • composables: 文件名与导出的组合式函数保持一致 (82b5e55)
  • docs: 文档重排为开始、指南、AI、写作、组件、参考六区 (d7c9342)
  • github: 统一 GitHub 配置默认值与 API 访问 (3c9b9f3)
  • i18n: 抽取 filterValidLocales 纯函数便于测试 (7263192)
  • mdc: 拆分 873 行的 transformMDC (2dbc7e1)
  • types: 解除核心代码对可选功能的类型依赖 (7195ca8)
  • 抽取 useDocsShell 消除 app.vue 与 error.vue 的重复 (2346be4)
  • 文档固定位于 content/docs 与 /docs 前缀 (64d98d5)
  • 文档站与模板改用 app.config 声明导航 (9d5af19)
  • 移除发布包中的作者私有配置 (51ff5e9)

✅ Tests

  • e2e: raw markdown 快照忽略提交历史链接中的分支 (9eac4e0)
  • e2e: 覆盖 app.config 导航的本地化与激活状态 (1f99519)
  • 引入 vitest 单元测试、Playwright 冒烟与模板构建脚本 (451a2bc)
  • 新增全部可选功能关闭的构建夹具并纳入 CI 矩阵 (acfd550)

📦 Build System

  • deps: 默认关闭功能的依赖改为 optional peer (2947011)
  • layer: 声明 engines.node >=22.5 (646062e)
  • release: 合并 release-it 配置并要求干净工作区 (3393698)

👷 CI

  • 拆分 check / docs / templates 三个 job (9247194)

🔧 Chores

  • docs: 新增 nuxtseo-layer-devtools 开发依赖 (6b76210)
  • 新增上游同步记录、issue 与 PR 模板并收紧依赖更新策略 (e8f57bf)
  • 移除 CLAUDE.md (8ff7ea0)
Copyright © 2024 - 2026