跳到主要内容

贡献指南

环境准备​

  1. 克隆

为了方便改进 Starcoin Cookbook, 首先需要 fork 到自己的账户下，然后 clone 文档的源码到本地。

git clone [email protected]:your-username/starcoin-cookbook.git
cd starcoin-cookbook
  1. 安装

你的机器上需要预先安装好 Node.js 以及 yarn，安装方式请参看 yarnpkg。

然后在项目目录下运行下面的语句安装依赖：

$ yarn
  1. 本地热加载开发

在项目目录下运行以下命令：

$ yarn start

这样子默认是启动英文版。如果想热加载其他语言版本，比如中文zh，可以

$ yarn start --locale zh
提示

可选的 locales 标识在 docusaurus.config.js 中定义。

此命令将自动打开浏览器并跳转到文档首页，当你编写或者修改文档时浏览器会自动刷新。

  1. 完整构建文档并浏览

（1）运行以下命令进行完整构建，它同时会构建出多个语言的完整文档：

$ yarn build

默认构建出的文档的 BaseUrl 是 /starcoin-cookbook, 如果你想改变它，可以在 build 之前通过环境变量指定。

$ export BASE_URL='/'

（2）运行以下命令，将在本地启动一个 Web 服务：

$ yarn serve

在浏览器中打开地址 http://localhost:3000/starcoin-cookbook/，就可以看到完整的文档。如果你指定了 BASE_URL 环境变量为 /，地址将是：http://localhost:3000/。

  1. 提交 Pull Request

（1）创建分支

创建简洁而具有描述性的分支，在该分支上进行编辑修改。

（2）推送

将自己修改好的内容提交并推送到远程仓库，在 GitHub 的页面会看到相应的拉取请求（Pull Request）提示，提交请求即可。

GitHub Action 会自动触发构建任务，检查文档。待文档被 Review 并合并到主分支后，文档会被自动部署并发布。

文档规范​

结构规范​

  1. 文档的目录名和文件名前面都有个数字前缀，比如 01-build.md，用来表示文档在左侧菜单中的顺序。
  2. 文档目录以及文档名中间的多个词语用 - 连接。
  3. 每个目录中的 README.md 表示该目录的首页。
  4. 每个目录中的 _category_.yaml 为该目录的配置文件，其中的 label 属性表示该目录在左侧菜单中展示的标题。
  5. 默认文档是英文，中文文档在 i18n/zh/docusaurus-plugin-content-docs/current 目录下，需要建立和英文文件同名的文件。

内容规范​

请参考Starcoin 技术文档的写作规范

常见问题​

  1. 如何翻译目录

新增目录后，运行以下命令：

$ yarn write-translations --locale zh

你会发现文件 i18n/zh/docusaurus-plugin-content-docs/current.json 已经变更了，新的目录名项目已经增加，编辑该文件进行翻译即可。