From 9412afcdfd1a808ff8311fb8cd5b98a5692eaa7b Mon Sep 17 00:00:00 2001 From: Caspar Zhang Date: Tue, 7 Jun 2022 15:15:25 +0800 Subject: [PATCH] add rules for titles Signed-off-by: Caspar Zhang --- articles/106-contribute-to-docs.md | 37 +++++++++++++++++------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/articles/106-contribute-to-docs.md b/articles/106-contribute-to-docs.md index babdc25..22403af 100644 --- a/articles/106-contribute-to-docs.md +++ b/articles/106-contribute-to-docs.md @@ -2,11 +2,11 @@ 龙蜥开发者文档中心本身也是龙蜥社区开源项目之一，依托 Gitee 平台，接受对文档相关内容的 [Issues](https://gitee.com/anolis/docs/issues) 和 [PR(Pull Requests)](https://gitee.com/anolis/docs/pulls) 提交，最终通过 [Gitee Pages](https://gitee.com/help/articles/4136) 平台分发。本文介绍如何参与到文档贡献者行列中来。 -## 0. 本文涵盖和不涵盖的范围 (Scope) +## 1. 本文涵盖和不涵盖的范围 (Scope) 本文仅介绍如何通过 Gitee 向龙蜥开发者文档中心（本站）贡献文档，不涵盖 SIG 组自行组织的内部文档，也不涵盖 [Anolis OS 语雀官方文档](https://yuque.com/anolis-docs)。但是文档规则很多时候是通用的，本文的规范要求很多时候可以复用到其他文档中去。 -## 1. 本站组织结构 +## 2. 本站组织结构 本站的文档通过 Gitee 管理，源码存放在 [https://gitee.com/anolis/docs/](https://gitee.com/anolis/docs/). 文档通过 Gitee Pages 提供的渲染功能，使用了一个简单的 Jekyll 模板直接渲染。渲染后的页面在 [https://anolis.gitee.io/docs](https://anolis.gitee.io/docs). @@ -44,9 +44,9 @@ 本站文档正式发布分支为 `main` 分支，所有的文档代码都应当通过 PR(Pull Requests) 方式提交，经过评审(Review)通过后，合并到 `main` 分支。 -## 2. 参与协作的方式 +## 3. 参与协作的方式 -### 2.1 准备工作 +### 3.1 准备工作 首先，你需要注册 Gitee 账号，同时需要在龙蜥网站签署 CLA 协议，也需要注册主站账号。相关账号注册和使用可以参考： + 《[101 - 社区账号指南](../articles/101-accounts.md)》 + 《[202 - Gitee 平台使用指南](../articles/202-intro-to-gitee.md)》 @@ -55,7 +55,7 @@ + 《[Gitbook 中文版](https://git-scm.com/book/zh/v2)》 + 《[Gite 帮助中心](https://gitee.com/help/articles/4122)》 -### 2.2 了解有哪些文档任务可以参与 +### 3.2 了解有哪些文档任务可以参与 常见的文档任务有：文档内容修正、文档翻译、主题文档编写等。想要了解详细的正在进行中的文档任务，可以访问[文档 SIG 组](https://openanolis.cn/sig/docs)，并建议参加 SIG 组的会议。 @@ -63,7 +63,7 @@ 领到具体 Issue 后，接下来你就可以基于这个任务进行文档开发了。 -### 2.3 进行文档开发 +### 3.3 进行文档开发 前面提到，本站文档所有代码都需要通过 PR 提交，为了便于开发，在进行代码开发前，建议先将本站的源码 fork 到自己的工作空间中，以避免自己的改动意外影响到本站内容。当然，我们已经对官方仓库进行了权限控制，可以最大程度防止意外改动。 @@ -84,7 +84,7 @@ Markdown 文档不支持直接插入图片，如需加入图片，需要先保 ![Gitee Pages 配置](../images/106-use-gitee-pages.png) -### 2.4 提交文档审核 +### 3.4 提交文档审核 在完成文档编写及调试后，需要在 Gitee 页面提交 PR. 发起 PR 的仓库应当是你自己的工作仓库，否则可能会找不到待合并仓库或分支。 @@ -99,15 +99,15 @@ PR 页面的入口位于 Gitee 页面上方标签页醒目位置，或者直接 ![创建 PR](../images/106-create-pr.jpg) -### 2.5 审核文档 +### 3.5 审核文档 审核人员在收到审核请求后，会仔细检查文档的内容和格式是否符合要求。在确认符合要求后，会通过审核。文档将会自动更新到本站页面中。 -## 3. 文档格式要求 +## 4. 文档格式要求 本章节列出了文档编写过程中的一系列要求。如前面所说，这些要求一定程度上也适用于其他文档的开发工作。 -### 3.1 术语规范 +### 4.1 术语规范 OpenAnolis 龙蜥社区相关的术语有如下规范： @@ -124,17 +124,22 @@ OpenAnolis 龙蜥社区相关的术语有如下规范： 在第一次出现相关术语的时候，建议使用完整名称，此后可使用简称。 -### 3.2 文档写作规范 +### 4.2 文档写作规范 1. 文档的标题应当为一级标题，即使用 Markdown 语法中的 `#` 号。本文档中所有其他标题，都不应再使用一级标题； -2. 文档编写过程中，不要求换行（例如100字换行，80字换行），而且我们也不推荐换行操作，对于不同 Markdown 渲染器，换行带来的格式影响是不一致的； -3. 中英文、中文数字混排，**必须**要用空格。即，中文和英文之间，应当使用一个半角空格；中文和数字之间，应当使用一个半角空格。举例如下： +2. 文档的各级标题应当用序号标识，请注意序号应当从 1 开始，避免使用标号 0； + 1. 一级标题举例: `## 1. 示例一级标题`; + 2. 二级标题举例: `### 1.1 示例二级标题`; + 3. 三级标题举例: `#### 1.1.1 示例三级标题`(如果还有下一层级)，或者 `#### a. 示例三级标题`(如果没有下一层级)； + 4. 不建议标题使用过多层级，尽量控制在三级及三级以内。 +3. 文档编写过程中，不要求换行（例如100字换行，80字换行），而且我们也不推荐换行操作，对于不同 Markdown 渲染器，换行带来的格式影响是不一致的； +4. 中英文、中文数字混排，**必须**要用空格。即，中文和英文之间，应当使用一个半角空格；中文和数字之间，应当使用一个半角空格。举例如下： ```md 接受 Reviewer 的检查 # 符合要求 基于PR提交 # 不符合要求 2015 年 10 月 1 日 # 符合要求 2013年3月 # 不符合要求 ``` -4. 嵌入图片的要求，在上一节已经说明； -5. 如果表示突出（但是没有很强烈的强调意味），可以用 `_内容_` 来实现斜体字；如果表示强调，可以用 `**强调**` 来实现粗体字； -6. 文件路径、命令、简短的代码需要使用反引号 '\`' 引用为 inline-quote。例如：`/etc/os-release`, `./execute.sh`；如果是大段代码，需要使用单独的 '\`\`\`' 代码块，并推荐注明对应的代码所属语言。 +5. 嵌入图片的要求，在上一节已经说明； +6. 如果表示突出（但是没有很强烈的强调意味），可以用 `_内容_` 来实现斜体字；如果表示强调，可以用 `**强调**` 来实现粗体字； +7. 文件路径、命令、简短的代码需要使用反引号 '\`' 引用为 inline-quote。例如：`/etc/os-release`, `./execute.sh`；如果是大段代码，需要使用单独的 '\`\`\`' 代码块，并推荐注明对应的代码所属语言。 -- Gitee