跳到主要内容

SOP：把本地 Markdown 文件夹发布成站点

目标​

  • 把一个本地 Markdown 文档集合批量导入到本站 docs/，并保持目录结构不变
  • 自动为每个目录生成 Docusaurus 的 _category_.json（用于侧边栏分组/排序/索引页）
  • 允许后续把更多文档集合按同样流程上线

推荐的目录规范（可选但强烈建议）​

  • 用数字前缀控制顺序：01-...、02-...
  • 用 README.md 作为目录首页（导入时会自动重命名为 index.md）
  • 图片等附件与 Markdown 同目录放置（相对路径引用即可）

一键导入（当前这套手册）​

pnpm import:handbook

通用导入（将来复用）​

pnpm import:docs -- --src "/abs/path/to/你的Markdown文件夹" --docs ./docs --clean

可选参数：

  • --dest-subdir handbook：导入到 docs/handbook/（不污染 docs/ 根目录）
  • --no-clean：不清空目标目录，做增量合并（谨慎使用，避免同名覆盖）

本地预览与构建​

pnpm start
pnpm build
pnpm serve

这个 SOP 做了什么（实现细节）​

  • 脚本：scripts/import-markdown-folder.mjs
  • 忽略：隐藏目录/文件、.git、.obsidian、node_modules 等
  • 规则：README.md/README.mdx → index.md/index.mdx
  • 生成：每个目录写入 _category_.json，并从 01-xxx 解析 position
  • 兼容：自动转义比较符号（如 <10%）以避免 MDX 解析报错
  • 链接：把相对的 *.md 链接改写成站内路由（同时去掉数字前缀）
  • 补齐：发现有链接但目标文件缺失时，自动生成占位文档（可用 --no-create-missing 关闭）