Skip to main content

文档维护

本文档维护在 go-kratos/go-kratos.dev 仓库中，采用 docusaurus 作为文档系统。仓库内容更新后，会自动触发 Github Actions 对文档进行生成和部署。

添加/修改文档​

首先 fork 文档仓库，并 clone 到本地。

然后在 docs 目录中的对应子目录下可以添加或修改相应的文档。文档格式为 Markdown，并支持一些扩展的语法，具体支持的语法请参考 Docusaurus: Markdown Features

注意下列事项：

  • 文档正文的子标题请使用二级或更低等级的标题，即##或###等，避免使用一级标题。
  • 对于文档内其它页面可以直接通过类似[document in a subfolder](subfolder/doc3.md)进行引用
  • 如果添加了新的文档，请按照后文的说明进行侧边栏的修改，以便文档能够展示在侧边栏中。

提交到 Github 后，向源仓库main分支发起 Pull Request, 等待维护团队合并。

修改侧边栏​

侧边栏的条目维护在文件 sidebars.js 中，如果需要修改侧边栏，请编辑此文件。 将docs下面的目录名和文档 id 填入 json 中。

该文件的具体配置方法请参考 Docusaurus: Sidebar

文档翻译​

如果您要维护多语言翻译，请将文档仓库 clone 到本地。

在i18n目录下的对应语言目录，如英文版本在i18n/en/docusaurus-plugin-content-docs/current可以找到或创建与docs目录对应的文件，注意 id 要与docs中对应文件的 id 相同。进行相应的文档翻译后提交即可。

具体文档翻译功能的扩展使用，请参考 Docusaurus: i18n - Using git

文档规范​

  • 内容要完整，需要充分体现组件的功能，并附带简要的示例或者示例的链接。力求达到用户看文档即可答疑。
  • 代码的缩进，一定要设置为空格缩进再复制。
  • 层级目录采用 Google AIP 结构。
  • 对于中文内容，数字与中文、中英文之间需要添加空格，具体参照中文文案排版。对于英文内容，标点符号和后文之间需要加空格，例如 Hello Kratos. Its my PR.。推荐使用 Prettier 之类的 formatter 进行格式化。
  • 在 commit 前尽量减少 diff，以减轻 review 的负担。
  • 因为各个平台默认的 行分隔符(EOL) 不相同，为了防止 commit 时出现大面积的 diff，请统一将编辑器的 End Of Line(EOL) 选项改为 LF(\n)。
  • Kratos 统一写法。K 大写。
  • 翻译完自己读一遍，要通顺，要能理解。不追求严格一致，可以意译。review 的时候也会检验。不会翻译的词汇可以不翻译，review 的时候会查看。翻译完还是要自己先 review 一遍，不要出现遗漏段落。