跳到主要内容

Markdown 到 Docusaurus 发布流程

用统一脚本批量搬运 Markdown，并快速上线到 Docusaurus。下面的步骤可复用到其他文档集，只需要替换源目录与目标目录。

1. 准备 Markdown 源​

  • 将原始 Markdown 放在同一目录下，文件名尽量带有数字前缀（00-主题.md），便于自动排序。
  • 确保文件首行是一级标题；如果已有 Front Matter，会被保留并优先使用。

2. 一键导入​

默认导入当前仓库里的数码选购指南：

pnpm run import:guide

自定义导入路径与目标目录：

node scripts/import-handbook.js <源目录> <目标目录> --clean
# 例：node scripts/import-handbook.js ../../lhqs-handbook/AI内容咸鱼销售系统 docs/ai-sales --clean

说明：

  • --clean 会先清空目标目录，保证版本干净。
  • 自动为没有 Front Matter 的文档写入 sidebar_position 与 sidebar_label，排序优先使用文件名前缀数字。

3. 本地预览与校验​

pnpm install          # 首次或依赖更新后执行
pnpm start            # 本地预览，热更新
pnpm build            # 构建验证，确保部署可用

检查点：

  • 侧边栏顺序是否与预期一致。
  • 中文路径/标题在地址栏与面包屑展示是否正常。
  • 代码块、表格、图片等在亮/暗色模式下的对比度。

4. 部署建议​

  • CI/CD：构建命令 pnpm build，静态产物在 build/。
  • 托管：可直接部署到 Vercel/Netlify 或挂在任意静态服务器（Nginx、Cloudflare Pages）。
  • 如果启用搜索插件（Algolia DocSearch 等），在变更导航结构后同步更新索引。

5. 常见扩展​

  • 新增其他专题：复用脚本到 docs/<topic>，并在 sidebars.ts/导航中挂接。
  • 多语言：在 docusaurus.config.ts 的 i18n.locales 中追加语言，并给各文档补充对应翻译。
  • 自定义样式：在 src/css/custom.css 追加主题变量或组件级样式，保持文档风格统一。