| name | init-shadcn-docs-nuxt |
| description | 初始化或重构任意组件库/项目的 `shadcn-docs-nuxt` 文档站。用于快速建立可运行、 可构建、可维护的 Nuxt 文档底座，并规避常见误区（配置复杂化、模块兼容、 MDC 语法错误、Windows 构建假卡死）。当用户提及"搭建组件库文档" "接入 shadcn-docs-nuxt""重做 Nuxt 文档站""迁移文档模板"时触发。 |
| user-invocable | true |
| metadata | {"version":"1.0.0"} |
初始化 shadcn-docs-nuxt 组件库文档
以"最小可用 + 快速稳定"为目标，给任意项目建立可长期维护的 shadcn-docs-nuxt 文档站。
本技能拆分为三层：
- SKILL.md — 导航与流程
- references/ — 排错手册与配置说明
- templates/ — 可直接复制的代码模板（含完整注释，注释即文档）
执行时按流程推进，遇到配置细节查 reference，需要代码直接读 template。
模板文件索引（templates/）
代码模板包含完整的注释说明，注释中记录了每个配置项的根因、不配置的后果、以及历史事故。使用时直接读取模板文件，不要跳过注释。
参考文档索引（references/）
核心原则（5 条铁律）
- 保持精简：
nuxt.config.ts 和 app.config.ts 先最小化，不先堆功能。
- 先跑通再美化：优先确保
dev / build 稳定，再做样式和内容扩展。
- 先修运行链再修样式：交互异常（暗黑模式、侧边栏折叠失效）先查 hydration 和模块导入报错，不要先改 CSS。
- 避免错误扩展：不要第一时间折腾 i18n / icon 自定义方案，先使用模板默认可用路径。
- 内容语法严格：MDC 容器语法要标准化，参见
references/mdc-prettier.md。
历史事故强约束（6 条记忆）
执行本技能时，必须默认带着这些"已发生过"的事故记忆：
- 不要假设 workspace 组件库已经先构建完成；文档站需要能直接从源码启动。→ 见
references/workspace.md
- 不要把交互失效先归因到样式；先排除 hydration 被模块导入错误打断。→ 见
references/compat.md
- 不要让 prettier 改写
content/**/\*.md 的 MDC 结构。→ 见 references/mdc-prettier.md
- 不要在 Windows 下把"日志停住"直接判定为"进程卡死"，先排查残留子进程。→ 见
references/windows.md
- 不要一开始就重写 i18n / icon 体系；先拿模板默认链路跑通。→ 见
references/nuxt-config.md
- 不要直接启用
ogImage 模块；会触发 vue.runtime.mjs does not provide an export named toValue 的 500 错误。→ 见 references/nuxt-config.md
推荐参考仓库优先级
按以下顺序学习并抽取配置（从高到低）：
nuxt-umami-docs（真实项目的稳定配置范式）shadcn-docs-nuxt-starter（最小骨架）shadcn-docs-nuxt（框架源码，仅用于查默认行为）shadcn-docs-ui-thing（组件库扩展思路，谨慎吸收）
每个仓库重点优先阅读这 6 个文件：package.json → nuxt.config.ts → app.config.ts → tailwind.config.* → assets/css/* → content/index.md
标准落地流程
第 1 步：建立最小骨架
docs-site/
├─ package.json
├─ nuxt.config.ts
├─ app.config.ts
├─ tailwind.config.js
├─ assets/css/
│ ├─ tailwind.css
│ └─ main.css
├─ content/
│ └─ index.md
├─ shims/ ← 按需，仅当 debug 兼容问题出现时
│ └─ debug.ts
├─ components/content/ ← 按需，自定义 MDC 组件
└─ plugins/ ← 按需，注册 workspace 组件库
如果是重构已有文档站，先保留现有 content/ 层级，不要和"底座重建"混在一次改动里。
第 2 步：依赖与脚本
详见 references/workspace.md § package.json 基线。
核心要点：
- 依赖：
nuxt、shadcn-docs-nuxt、vue、vue-router、tailwindcss、tailwindcss-animate
- 如需消费 workspace 组件库，补
workspace:* 依赖
- devDependencies：
@iconify-json/lucide（Nuxt Icon 必需）
- 脚本必须包含
predev / prebuild / postinstall 三处 nuxt prepare
第 3 步：Nuxt 配置
详见 references/nuxt-config.md。
先用最小骨架启动，遇到客户端报错再按"按需补丁"策略逐项补兼容。
第 4 步：Tailwind + CSS
详见 references/tailwind-css.md。
硬性检查：content 扫描必须覆盖 node_modules/shadcn-docs-nuxt，否则主题类缺失、暗黑样式异常。
第 5 步：MDC 内容
详见 references/mdc-prettier.md。
第 6 步：验证
执行后至少提供以下证据：
| 验证项 | 方法 |
|---|
| 启动 | pnpm --filter <pkg> dev → 首页 HTTP 200 |
| 构建 | pnpm --filter <pkg> build → 有 .output 产物 |
| 交互 | 暗黑模式切换、侧边栏折叠可用 |
| 内容 | 抽查至少 1 个 ::demo-playground 页面，无裸 marker 文本 |
| console | 无阻断 hydration 的 error |
常见故障排查顺序
交互失效（暗黑模式切换失败、侧栏按钮无效）时，严格按此顺序：
- 先看浏览器 console 是否有模块导入错误 →
references/compat.md
- 再修依赖入口兼容（alias / optimizeDeps / dedupe / ssr.noExternal）
- 最后再做 Tailwind / 主题样式检查 →
references/tailwind-css.md
构建卡住时 → references/windows.md
MDC 裸文本 / hydration mismatch → references/mdc-prettier.md
禁改项（无明确证据前不动）
extends: ["shadcn-docs-nuxt"]（它通常不是根因）- 内容目录层级（底座改造阶段避免和内容重排耦合）
- i18n 多语言路线（单语文档站先保持最小配置）
- icon 体系大改（先沿用模板可用默认方案）
ogImage: { enabled: false }（直接启用会触发 500）
反模式清单
- 先写大量"自定义配置"，最后才验证能否启动。
- 用样式改动掩盖运行时导入错误。
- 批量格式化
content/**/*.md 后不做页面与 console 回归。
- 在同一轮同时重排内容架构 + 重构底座，导致回归不可定位。
- 只报"看起来好了"，不附任何可重复验证证据。
- 把
::demo-playground 写成 ## ::demo-playground。
- 在 Windows 下把"日志停住"直接判定为"进程卡死"而不先清理旧进程。
输出要求
执行本技能时，最终至少给出：
- 关键改动文件列表（配置、样式、内容）
- 运行与构建验证结果
- 若有风险项，给出下一步最小补救建议
