cklwblove VitePress 课程工具配置
面向使用 @smart-cs/vitepress-course-tools 的 VitePress 文档站。目标：磁盘上的 docs/zh/**/*.md 与导航、PDF 封面目录、商品详情页保持一致，并补齐 npm 导出命令。
涉及文件
| 文件 | 作用 |
|---|---|
docs/zh/**/*.md |
文档真源（以磁盘为准） |
docs/.vitepress/config.mts |
网站侧栏 / 导航 link |
vitepress-course-tools.config.ts |
PDF、封面、商品详情、截图 |
scripts/export-site-utils.ts |
旧版导出脚本中的 ZH_*_DOCS 列表（若存在） |
shared/course-theme-class.ts |
主题 class，勿在 VitePress 客户端 import 完整 config |
package.json |
pdf:* / screenshots:* / code:pack 脚本 |
basePath（config）须与 docs/.vitepress/config.mts 的 base 完全一致。
工作流
进度：
- [ ] 1. 扫描 docs/zh 实际 .md 文件
- [ ] 2. 同步 docs/.vitepress/config.mts 侧栏
- [ ] 3. 同步 vitepress-course-tools.config.ts → cover.tocManifest
- [ ] 4. 同步 scripts/export-site-utils.ts（若项目仍使用该文件）
- [ ] 5. 配置或更新 productDetail
- [ ] 6. 确认 package.json 导出脚本与依赖
- [ ] 7. 校验（可选运行导出）
1. 扫描 docs/zh
find docs/zh -name '*.md' | sort
区分：
- 根目录技术文档：
index.md、00-*.md…10-*.md - 面试资料：
interview/*.md
侧栏显示名通常取自文件名（去掉序号前缀与 .md），或与现有 text 字段风格保持一致。
2. 同步侧栏（config.mts）
在 zhGuideItems / zhInterviewItems 中：
- link 格式：
/zh/文件名.md或/zh/（index） - text：与文档标题或文件名语义一致
- 顺序：
index→ 编号技术文档 →interview/子目录按文件名排序
常见错误：link 指向已改名/删除的文件（如 05-八股文-医疗AI专题.md 实际为 05-八股文-AI专题.md）。
英文侧栏 enGuideItems 仅在 docs/en/ 存在对应文件时维护。
3. 同步 cover.tocManifest
在 vitepress-course-tools.config.ts 的 cover.tocManifest 中，条目顺序与侧栏一致：
{ title: '侧栏 text', routePath: '/zh/路由' }
routePath 规则（cleanUrls: true）：
index.md→/zh/00-项目概览.md→/zh/00-项目概览（无.md后缀）interview/01-简历写法模板.md→/zh/interview/01-简历写法模板
title 与侧栏 text 对齐；routePath 与包内 sourceFileToRoutePath 一致。
4. 同步 export-site-utils（若存在）
scripts/export-site-utils.ts 中的 ZH_GUIDE_DOCS、ZH_INTERVIEW_DOCS 须与侧栏顺序一致，但值为相对 docs/zh/ 的路径（含 .md）：
'index.md',
'00-项目概览.md',
// ...
'interview/01-简历写法模板.md',
readmeScreenshotTargets 的 routePath 同样用 cleanUrls 格式。
5. 配置 productDetail
在 vitepress-course-tools.config.ts 增加 productDetail（类型 ProductDetailConfig）。
与 cover 的关系：
title/subtitle可与cover.mainTitle/subTitle对齐- 未写
intro时导出回退到cover.descCn - 未写
tocSections时回退到pdf.tocGroups或自动生成
intro 写法（包内渲染规则）：
| 语法 | 效果 |
|---|---|
| 空行 | 分段 |
行首 🔹 / ## / 【标题】 |
小节标题 |
行首 • - * |
列表 |
| 普通行 | 段落 |
tocSections：按侧栏分组（如「技术文档」「面试资料」），每项 { title, note? }，标题与 tocManifest 一致，note 为一句卖点。
gallery：指向 screenshotsDir 下 PNG；路径相对项目根。与 screenshots 配置或 readmeScreenshotTargets 对齐。图片不存在时包内会回退占位图——正式发版前先跑截图。
exportVariants：['classic', 'minimal', 'card'] 或按需子集。
完整字段说明见 references/product-detail-fields.md。
6. package.json 脚本
依赖（Git 安装时无 dist，用 tsx 直跑 src/cli）：
"@smart-cs/vitepress-course-tools": "github:cklwblove/vitepress-course-tools"
推荐脚本：
"pdf:export": "tsx node_modules/@smart-cs/vitepress-course-tools/src/cli/pdf-export.ts --phase=all",
"pdf:export:sections": "... --phase=sections",
"pdf:export:cover-toc": "... --phase=cover-toc",
"pdf:export:merge": "... --phase=merge",
"pdf:export:cover": "tsx node_modules/@smart-cs/vitepress-course-tools/src/cli/pdf-cover.ts",
"pdf:export:product": "tsx node_modules/@smart-cs/vitepress-course-tools/src/cli/pdf-product-detail.ts",
"pdf:build": "npm run docs:build && npm run pdf:export",
"screenshots:readme": "tsx scripts/capture-readme-screenshots.ts",
"code:pack": "tsx node_modules/@smart-cs/vitepress-course-tools/src/cli/pack-code.ts"
vitepress-course-tools.config.ts 顶部类型导入：
- 有 dist：
import type { CourseToolsConfig } from '@smart-cs/vitepress-course-tools' - 仅 Git 源码：改引
./node_modules/@smart-cs/vitepress-course-tools/src/types.ts
7. 校验
# 侧栏与磁盘一致（人工或 diff）
find docs/zh -name '*.md' | sort
# 整本课程 PDF（需先 build）
npm run docs:build
npm run pdf:export
# 商品详情 PDF（不依赖 build，但 gallery 图需存在）
npm run pdf:export:product
npm run pdf:export:product -- --variant classic
# README 截图 → productDetail.gallery
npm run docs:build && npm run screenshots:readme
成品路径：
- 课程 PDF：
artifacts/pdfs/<pdf.name>-guide-zh.pdf - 商品详情：
artifacts/pdfs/<pdf.name>-product-*.pdf
新增 / 删除文档时的检查单
- 在
docs/zh/增删.md - 更新
config.mts对应zhGuideItems或zhInterviewItems - 更新
cover.tocManifest同序条目 - 更新
productDetail.tocSections（若有分组目录） - 更新
export-site-utils.ts的ZH_*_DOCS（若存在） - 新章节若需预览图：加入
screenshots/gallery/readmeScreenshotTargets
注意事项
- 勿在
docs/.vitepress/theme/index.js中 import 完整vitepress-course-tools.config.ts（会拖入 Node 依赖导致白屏）；主题 class 用shared/course-theme-class.ts docsBasePath在export-site-utils.ts可能与config.mts的base不一致，以 config.mts 为准 并统一- 虚拟商品文案注意平台合规：避免医疗执业、极限词、站外引流；详见项目内
品文案.md（若存在）
参考
- 包内 README：
node_modules/@smart-cs/vitepress-course-tools/README.md - 字段速查：references/product-detail-fields.md
- 同步关系图：references/config-sync-map.md