跳到主要内容

如何写文档

准备工作​

  1. 安装软件
  • Node.js 20.18.1 以上版本（你可以运行 node -v 来查看已经安装的版本号）
  • Yarn 1.22.22 以上版本（你可以运行 yarn -v 来查看已经安装的版本号）
  • git 最新版
  1. 获取公司项目安装包下载权限（一次就行）。在任意地方打开终端运行如下命令。然后会提示输入 Username 和 Password。 nexus 下载账号 Username 和 Password 请联系管理员获取。
npm login -registry=https://nexus.dev.bizops.com.cn/repository/npm-group/
  1. 到文档仓库 https://gitlab.dev.bizops.com.cn/product-core/icp-doc-website 使用 git 下载文档仓库到本地。（如果没有账号请询问管理员，或者让人直接给你下载的 zip 包）
  2. 进入文档跟目录 (package.json 文件所在的顶层文件夹) 运行以下命令安装依赖。
yarn
  1. 安装依赖成功过后，运行以下命令启动本地文档服务。
yarn start

当看到 http://localhost:3000/icp-doc/docs 的网址自动在浏览器打开的时候，说明文档服务启动成功，准备工作已完成。

中文文档​

一般来说，没有特殊需求，文档的 markdown 文件和访问网页是一一对应的。

比如 ACL 的配置文档 http://localhost:3000/icp-doc/docs/platform/frontend/use-component/use-acl 对应本地文件系统目录 docs/platform/frontend/use-component/use-acl.md, 直接修改 markdown 文件网页会自动刷新。

如果要添加文档，直接建文件夹和对应的 markdown 文件即可。

修改完成通过 git 提交到仓库即可。等十分钟左右线上 https://duxing.cn/icp-doc/docs/ 就会更新最新文档。

英文文档​

本地只能同时自动一种语言的服务，要撰写英文文档，保证通过 yarn 命令启动的中文文档服务已经停止。（windows 系统 ctrl+c 停止服务，mac 系统 command+c）

重新运行以下命令启动英文文档服务：

yarn start --locale en

英文文档的地址在本地文件系统的 i18n/en/docusaurus-plugin-content-docs/current 目录下，和中文文档一一对应。

例如，中文的 ACL 配置文档在 docs/platform/frontend/use-component/use-acl.md，英文的则在 i18n/en/docusaurus-plugin-content-docs/current/platform/frontend/use-component/use-acl.md。

中文和多语言文档文件系统结构如下：

website
│
│ # 中文文档地址
├── docs
│   └── platform
│       └── frontend
│           └── use-component
│               └── use-acl.md
│
│ # 多语言文档地址
├── i18n
│   └── en
│       └── docusaurus-plugin-content-docs
│           └── platform
│               └── frontend
│                   └── use-component
│                       └── use-acl.md
│
└── package.json

同样，修改完成通过 git 提交到仓库即可，不用做额外操作。

如果没有 git 账号无法提交代码，将翻译好的 /i18n/en/docusaurus-plugin-content-docs 下的所有文件打包联系发送给 张东（dong.zhang@bizops.com.cn)

文档特殊排序、修改顶部菜单等特殊需求​

如果有特殊需求，比如文档排序，修改顶部菜单等，可以研究 docusaurus.config.js 和 sidebars.js 文件。

如果有疑问，联系 张东（dong.zhang@bizops.com.cn)