跳到主要内容

批量导入与发布SOP

目标​

将本地 Markdown 文档集合稳定转换为 Docusaurus 文档站，并保留清晰的目录结构与顺序。

前置条件​

  • Node.js 20+
  • pnpm

约定规范​

  • 文件命名建议：01-标题.md，使用数字前缀控制排序。
  • 避免同一章节出现多个版本（脚本会自动去重，优先保留 - 或 _ 的版本）。
  • 标题请使用 # 作为文档主标题，Docusaurus 会自动读取为页面标题。

导入步骤​

  1. 准备本地文档目录（例如：/path/to/你的文档集）。
  2. 执行导入脚本：
SOURCE_DIR="/path/to/你的文档集" pnpm import:handbook
  1. 本地预览：
pnpm start
  1. 生产构建：
pnpm build

脚本行为说明​

  • 默认导入到 docs/handbook。
  • 自动清理旧内容（如需保留旧内容，可设置 CLEAN_DEST=0）。
  • 自动跳过命名格式为 12. 标题.md 的重复版本。
  • 自动转义 < 等比较符号，避免 MDX 解析报错。

发布建议​

  • 结合你的部署平台（如 GitHub Pages / Vercel / Netlify）设置构建命令：pnpm build。
  • 构建产物输出在 build/。