跳到主要内容

SOP：把本地 Markdown 文档集变成可访问的网站

本项目基于 Docusaurus + pnpm，并内置一条「可复用」的导入流程：把任意 Markdown 文件夹批量导入到 docs/<collection>/，自动补齐 Docusaurus 所需的 front matter、按数字前缀排序、修复相对链接、同步图片/附件资源。

1) 初始化/启动​

pnpm install
pnpm start

2) 导入一个文档集（推荐：导入到子目录）​

选择一个集合标识（collection），用于站点路由与文件归档：

  • 目标目录：docs/<collection>/
  • 路由前缀：/<collection>

命令模板：

pnpm import:md -- --src "/abs/path/to/markdown-folder" --dest "docs/<collection>" --slug-base "/<collection>" --category-label "文档集名称" --clean

参数说明：

  • --src：本地 Markdown 根目录（可包含子文件夹）
  • --dest：导入到 Docusaurus 的 docs 子目录
  • --slug-base：统一给该文档集加路由前缀，避免多个文档集之间的 slug 冲突
  • --category-label：侧边栏里该目录显示的名称（建议用中文）
  • --clean：清空 --dest 后再导入（不会影响其它 docs）

3) 排序与导航规则（约定）​

为了得到稳定的目录顺序，建议源文件名使用数字前缀：

  • 00-目录导航.md（会导入为 intro.md）
  • 01-xxx.md、02-xxx.md ...

导入脚本会：

  • 从文件名提取 sidebar_position（用于 sidebar 排序）
  • 从文件名提取 sidebar_label（用于侧边栏显示）
  • 自动生成 slug：
    • 00-* → /<collection>/
    • 01-* → /<collection>/01（以此类推）
    • 部分常见页面（如 FAQ/工具包）在脚本内置了更语义化的 slug（可自行改）
  • 自动处理 MDX 兼容性：将正文里的 "<1"、"<3㎡" 这类比较符号转为 &lt;1，避免构建报错

4) 发布​

构建静态站点：

pnpm build

产物在 build/，可部署到任意静态托管（如 GitHub Pages / Netlify / Vercel / 自建 Nginx）。