Markdown语法规范

标题和章节

---
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 依赖

**结果： ** 按照以下步骤创建工程：

1. 准备开发环境
   • JDK 7 或 JDK 8
   • Apache Maven 3.2.5 或以上版本
2. 构建工程模板
   1. 子步骤1
   2. 子步骤2
3. 引入 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
• 正确：``

禁止涉及性别、法律、文化等

• 不要使用“他、她、他/她”等有性别指代的词。优先改写句子，不可避免时，使用复数“他们”或者“用户”。
• 不要提及圣诞、春节等有特定文化背景的场景。