Markdown 规范的书写格式使文档更容易理解

Markdown 书写规范

  本文有助于您规范使用 Markdown 语法规则，使您的文档更容易理解。虽然不是必需的，但很快您就会发现，这些规则很好的兼容了各种 Markdown 编辑器，能够准确地为您呈现文档内容。

标题

• 整篇文档只能有一个顶级标题，并且要放在文档首行；
• 标题符号要从行首开始，位于块引用和代码块中的标题符号除外；
• 标题符号和标题文本之间要留出空格，并且只能有一个空格；
• 标题相邻的上、下行要留出空行，位于文档首行和末行时除外；
• 标题等级每次只能增加一个级别，不要越级使用；
• 标题行行尾不要使用中、英文标点符号，包括：逗号、句号、分号、冒号和感叹号；
• 整篇文档不能有内容相同的标题行；
• 整篇文档要使用统一的标题符号。

无序列表

• 无序列表相邻的上、下行要留出空行，位于文档首行和末行时除外；
• 无序列表符号与列表内容之间要留出一个空格；
• 无序列表子项符号始终缩进两个空格；
• 同级别无序列表符号的缩进始终保持一致；
• 整篇文档要使用统一的无序列表符号。

有序列表

• 有序列表相邻的上、下行要留出空行，位于文档首行和末行时除外；
• 有序列表项要从 “0.” 或 “1.” 开始，并且始终按照数字顺序增加序号；
• 有序列表符号与列表内容之间要留出一个空格；
• 同级别有序列表符号的缩进始终保持一致。

表格

• 表格每行开头和结尾都要放置一个管道符；
• 表格每行单元格的数量必须保持一致；
• 表格相邻的上、下行都要留出空行，位于文档首行和末行时除外。

块引用

• 块引用符号和内容之间要留出空格，并且只能有一个空格；
• 块引用行间不能有空行，但允许在空行前添加一个块引用符号。

代码和代码块

• 代码符号与文本之间不能有空格；
• 代码块要指定内部的编码语言；
• 代码块相邻的上、下行要留出空行，位于文档首行和末行时除外；
• 代码块中的命令行应省略行首的美元符号，但有输出行时除外；
• 整篇文档使用统一的代码块格式（使用缩进或者使用符号）；
• 整篇文档使用统一的代码块符号（波浪号或者反引号）。

粗体和斜体

• 不要使用整行粗体或者整行斜体文本代替标题；
• 粗体、斜体符号与文本之间不能有空格；
• 整篇文档要使用统一的粗体和斜体符号。

URL 和 email

• URL 地址或者锚点不能是空的；
• URL 文本和地址的语法顺序不能颠倒；
• 自动链接的 URL 和 email 要放入一对尖括号中；
• 自动链接的 URL 和 email 与尖括号之间不能有空格；
• 自动链接的 URL 和 email 可以包装成 代码 来禁止跳转。

图片

• 应该为图片提供替代文本，当图片加载失败时显示这个文本。

分隔符

• 整篇文档应使用统一样式的水平分割符。

通用

• 不要在行末尾随无效空格，用作断行的空格除外；
• 不要使用制表符缩进，而应该使用空格缩进；
• 不要在段落间出现连续空行，位于代码块中时除外；
• 不要在单行中超过最大字符数限制（默认 80），URL 除外；
• 不要在文档中使用内联 HTML 元素，必要时除外；
• 应该使用正确的大小写书写专有名称；
• 应该使用换行符另起新行结束整篇文档。