-
Notifications
You must be signed in to change notification settings - Fork 185
Markdown语法规范
Jimmy song edited this page Jul 26, 2019
·
1 revision
---
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
- 正确:``
- 不要使用“他、她、他/她”等有性别指代的词。优先改写句子,不可避免时,使用复数“他们”或者“用户”。
- 不要提及圣诞、春节等有特定文化背景的场景。
© 2019 The SOFAStack Authors