Markdown语法规范 - sofastack/sofastack.tech GitHub Wiki
---
title: This is the title 文章标题
---
## This is heading 2 / 二级标题
### This is heading 3 / 三级标题
#### This is heading 4 / 四级标题
- 文章标题只在文档 front matter 中使用
title属性定义。不使用 heading 1 (#)。 - 章节标题使用 heading 2、3 或 4。尽量避免使用 heading 5 (
#####) 或更多层级的标题。 - 避免跳层级使用，即 heading 2 段落下的子标题应使用 heading 3 而不是 4。
- 避免手动给标题添加编号。手动编号增加维护成本。
- 英文标题使用 sentence case，只有首字母和专有名词大写。
这段文字 **加粗** ，也可以这样 __加粗__
这段文字 *斜体*
这段文字 ***加粗且斜体***- 介绍关键术语时使用 加粗，而不是 斜体 或“引号”。
- 避免对以下元素使用加粗或斜体。应统一使用行内代码
code模式标记以下元素：- 文件名
- 文件路径
- 方法名
- 参数、变量名
- URL
This is a [link to the SOFAStack projects](/projects).- 站内链接请使用相对路径。
- 链接文字应有明确意义，表明所指向的内容。
- 错误：
有关 SOFABoot 的更多信息，点击 [这里](#)。 - 正确：
有关 SOFABoot 的更多信息，参见 [SOFABoot 文档](#)。
- 错误：
- 说明为什么用户需要跳转，并把目的置于句首，方便读者判断是否需要跳过这一句。
- 错误：
查看 [xx文档](#) 了解更多配置详情。 - 正确：
要了解更多配置详情，查看 [xx文档](#)。
- 错误：
列表分为 有序列表 (ordered list) 和 无序列表 (unordered list)。
- 有序列表：强调顺序。如果列表中任意两条对换顺序会影响结果，则使用有序列表，否则使用无序列表。多用于操作步骤等场景。
- 无序列表：调整顺序不影响内容。多用于特性列表、必要条件列表等场景。
示例：
按照以下步骤创建工程：
1. 准备开发环境
- JDK 7 或 JDK 8
- Apache Maven 3.2.5 或以上版本
1. 构建工程模板
1. 子步骤1
1. 子步骤2
1. 引入 SOFABoot 依赖**结果： ** 按照以下步骤创建工程：
- 准备开发环境
- JDK 7 或 JDK 8
- Apache Maven 3.2.5 或以上版本
- 构建工程模板
- 子步骤1
- 子步骤2
- 引入 SOFABoot 依赖
在工程的 `pom.xml` 文件中添加配置 xxx以下类别的内容使用行内代码标记： - 文件名 - 文件路径 - 方法名 - 参数、变量名 - URL
This is a code block
-
指明代码语言
\```java```xml
```json
```sql
-
标明占位符
$ cd <your_path>/conf
> **说明：**
> 这是个说明。
> **重要：**
> 这是条重要信息。
> **重要：**
> - 不要使用引用格式展示代码内容。
> - 列表内容2 重要： 不要使用引用格式展示代码内容。应使用代码块 ``` 格式展示代码。
- 图片统一使用
png格式，源文件与引用该图的 markdown 文件放在统一目录下。 - 确保图片内容有对应的文字说明，防止读者遗漏图片中的重要信息。
- 插入图片时提供 alt text
- 不要以截图形式提供代码示例
- 在中文文档中使用中文全角标点。不要混用中英文标点。
这是一个句子。This is a sentence.使用省略号…… 而不是三个点... - 中英文之间保留一个英文空格。
中文和 English words 之间保留一个空格。
区分 "可以" / "必须"
-
可以（can / could）：表示用户有选择权，可以做也可以不做，或通过其它方法完成。
例如：
可以通过修改xx参数值完成yy设置可能引起的疑问：修改参数值是否为完成yy设置的必须步骤？不做会怎么样？默认情况是怎样的？修改参数是否是完成设置的唯一方法？其它方法是什么？如何选择？ -
必须（must）：表示必要条件，不做会影响结果。
例如：
要使用 SOFARPC，必须在工程中引入 xxx 依赖表示如果不引入依赖，将无法使用 SOFARPC。 - 需要（need）：避免使用。
谨慎使用 “一般”“正常”
例如：一般情况 是指怎样的情况？例外情况是怎样的？什么条件下会出现例外？例外如何处理？
- 错误：
这个配置没有什么特殊的,正常使用即可（去掉这句话不影响文意）
- 错误：
把它设为 true - 正确：
把xxx配置项设为 true
尽量使用祈使句 / 第二人称。 - 错误：“我们发送一个请求” - 正确：“发送请求”
- 为了让所有读者都更易读懂文档，尽量使用全称。例如：使用 Kubernetes, 而不是 k8s。
- 避免拉丁缩写，例如："i.e." "e.g." "etc." "et al."
- 错误：
请求被收到后，服务器开始执行xxx - 正确：
服务器收到请求后，开始执行xxx
例外：
- 强调状态而非动作。如：
确认文件已被保存。 - 没有必要提及主语或动作执行者。
- 错误：
没有管理员权限的用户不能删除文件。 - 正确：
要删除文件，用户必须拥有管理员权限。
- 错误：
xx参数告诉服务器要执行xxx - 正确：``
- 不要使用“他、她、他/她”等有性别指代的词。优先改写句子，不可避免时，使用复数“他们”或者“用户”。
- 不要提及圣诞、春节等有特定文化背景的场景。