后续添加文档，需要用到
git等操作，要准备github账号 和git工具
要查看添加
md文件后的展示效果还需要准备node.js（本地测试完才可以提交代码）
- 首先
fork主仓库, 会在个人账户下创建一个与原始项目一模一样的仓库副本, 在副本仓库操作，可以避免错误操作等带来的影响
- 在
git bash中执行克隆命令
git clone [URL] # 例如 git clone https://github.com/zgsm-ai/manual.git
3. 查看 `fork` 仓库的 `URL`， 选择 `HTTPS / SSH` 复制
大部分情况下， 直接 clone 会因为网络问题 clone 失败， 即便挂了科学上网， 设置系统代理可能也不行
两种解决方法
- 使用代理软件的
tun模式， 这种就相当于生成了一个虚拟网卡， 即透明代理 - 因为
cmd这种没遵循系统代理设置， 我们可以通过环境变量强制指定其使用我们的代理
cmd和bash设置环境变量有区别, 参考：
git bash:
export https_proxy=http://localhost:7890 # 7890 是clash的端口， verge应该是7897
export http_proxy=http://localhost:7890 # 这个加不加都行
cmd:
set https_proxy=http://localhost:7890 # 7890 是clash的端口， verge应该是7897
set http_proxy=http://localhost:7890 # 这个加不加都行
clone的总流程如下所示
- 接下来
cd到 克隆的项目下， 后续提交代码等操作即可在这里进行
// highlight-next-line
cd manual
# SXF-Admin@DESKTOP-4UHN77U MINGW64 /d/Users/SXF-Admin/Desktop/演示操作/manual (main)
# cd 后应该可以看到当前位于 main 分支
// highlight-next-line
git checkout -b feature/your-branch # 尽量不要在 main 或者 master 分支开发, 这里从 main 创建一个新的开发分支
# SXF-Admin@DESKTOP-4UHN77U MINGW64 /d/Users/SXF-Admin/Desktop/演示操作/manual (feature/add-md)
# 已经在你的个人分支上了
通过
git克隆后, 可以看到项目结构，这里只列举了需要关注的部分
manual-copy
├─docs
│ ├─guide
│ │ └─img
│ └─img
├─i18n
│ └─zh
│ ├─docusaurus-plugin-content-docs
│ │ └─current
│ │ ├─guide
│ │ │ └─img
│ │ └─imgdocs 下的 md 文件对应于英文文档, 在 i18n/zh/docusaurus-plugin-content-docs/current 下的 md 文件 对应于中文文档
不同文档结构在使用时会有点差别，先划分下两种结构
多个文档位于同一个标签（目录）下 -> 分组式结构， 如下
docs/
├── getting-started/
│ ├── installation.md
│ └── quota.md
每个文档对应一个标签 -> 扁平式结构， 如下
docs/
├── getting-started.md
├── installation.md
├── quota.md
└── usage-guide.md
在项目目录下执行命令， 安装开发所需的包
npm install
开发模式执行
npm run start
本地修改会实时同步到前端页面上， 适合调试， 但是存在个问题， 没法测试中英文文档切换和搜索等功能， 因此需要用到生产模式
依次执行
npm run build
npm run serve
这种缺点是没法实时看到修改的内容
文档和所在目录的命名不能存在空格，可以用‘-’
- 把准备好的英文版本的
md文件直接放在docs目录下, 图片等资源可以放在同级的img文件夹中 - 同样在
current也准备一份， 内容翻译为中文，最终结构如下：
manual-copy
├─docs
│ └─img
│ └─your.md
│ └─ ...
├─i18n
│ └─zh
│ ├─docusaurus-plugin-content-docs
│ │ └─current
│ │ └─img
│ │ └─your.md
│ │ └─ ..编写md文件需要加入下面的内容
---
sidebar_position: 3 # 该参数规定了当前文档在大纲中的位置， 需要放在md文件的开头
---
第一个 #（即一级标题）会作为大纲标题
实际效果对照
首先把md文件按照下列方式组织起来
manual-copy
├─docs
│ ├─guide
│ │ └─img
│ │ └─_category_.json
│ │ └─mdfile1.md
│ │ └─mdfile2.md
│ │ └─ ...
├─i18n
│ └─zh
│ ├─docusaurus-plugin-content-docs
│ │ └─current
│ │ ├─guide
│ │ │ └─img
│ │ │ └─_category_.json
│ │ │ └─mdfile1.md
│ │ │ └─mdfile2.md
│ │ │ └─ ...相比扁平式结构文档，需要增加 _category_.json 文件
# _category_.json
{
"label": "Getting Started", # 大纲标题 （不过在这里不起作用，需要继续向下看）
"position": 1, # 当前目录大纲位置
"link": {
"title": "Getting Started", # 大纲导航页标题 （不过在这里不起作用，需要继续向下看）
"type": "generated-index" # 自动生成大纲标题
}
} 涉及到中英文翻译，需要额外做一点操作， 这个是 docusaurus 本身存在的一点问题可以看这里的讨论
执行
npm run docusaurus -- write-translations查看 i18n/zh/docusaurus-plugin-content-docs/current.json, 将其中的英文翻译为中文
通过生产模式测试才可以提交pr
git add . # 准备处理全部改动
git commit -m "docs: add contributing guide" # 提交到工作区
# 如果主线有改动是本地没有的
# git pull --rebase origin main # 不要直接 pull 会多一次合并提交
git push -u origin feature/add-md:feature/add-md) # 这样会在github个人仓库新建一个feature/add-md分支并提交
完成上述操作后， 准备提交pr
首先检查下提交的内容和本地提交的是不是一致的， 点击后查看每个文件的改动
确认无误后， 点击：
确认下目标分支和提交分支是不是正确的， 没问题后， 点击create pull request, 遵守提交准则，即完成
合并到主线后会自动触发服务更新，可以在主仓库的 `Actions` 下查看