跳到主要内容

批量上网 SOP

这套 SOP 目标是把「本地 Markdown 文件夹」稳定转换成可在线访问的 Docusaurus 文档站，并支持后续持续增量导入。

目录约定（推荐）​

  • 一个文件夹 = 一个文档集合（一本手册/一组知识库）
  • 文件夹内可以是扁平结构，也可以是多级目录
  • 文档用 .md/.mdx；图片/附件放在同目录（相对路径引用）

一键导入（通用脚本）​

仓库内提供 scripts/import-docs.mjs，用于把任意本地文档文件夹复制到 Docusaurus docs/ 下（保留结构）。

pnpm import:docs -- --src "/ABS/PATH/你的文档集" --dest "docs/集合名" --clean --category-meta

参数说明：

  • --src：本地文档集目录（绝对路径/相对路径均可）
  • --dest：导入到仓库内的目标目录（建议 docs/<集合名>）
  • --clean / --no-clean：导入前是否清空目标目录（默认 --clean）
  • --category-meta：为目录生成 _category_.json，便于侧边栏分类展示
  • --dry-run：只打印/校验（不落盘）

本仓库：导入「租房装修完全指南」​

已配置快捷命令（路径可按需修改）：

pnpm import:handbook

发布前检查清单​

  • pnpm start 本地预览：侧边栏顺序/链接/图片是否正常
  • pnpm build 构建：确保没有 broken links 导致失败（当前为 warn）
  • 统一图片引用方式：优先相对路径，或放 static/ 用绝对路径 /...

MDX 兼容注意事项​

Docusaurus 会用 MDX 解析 .md，如果正文里有类似 (<10箱) 的写法，可能会被当作 JSX 导致编译失败。导入脚本会自动把 <数字 转成 &lt;数字，避免这类问题。

多文档集扩展建议​

  • 每新增一套文档：导入到 docs/<new-set>，并在 sidebars.ts 增加一个 category + autogenerated
  • 如需更友好的 URL（避免中文/空格编码）：可以在导入阶段统一重命名文件并补充 frontmatter slug