Releases
Release v3.0.0
Released on October 27, 2026
!WARNING@movk/nuxt-docs 3.0 是一个破坏性版本。
默认关闭的功能(组件文档、AI Chat、Mermaid、无障碍检查、国际化)改为 optional peer 依赖,文档固定位于
content/docs/,部分配置字段重命名,并以编辑式排版作为新的视觉默认值。缺少依赖或配置冲突会在构建期直接报错并给出原因。
亮点
- 按需依赖: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)