Markdown 书写规范
本文有助于您规范使用 Markdown 语法规则，使您的文档更容易理解。虽然不是必需的，但很快您就会发现，这些规则很好的兼容了各种 Markdown 编辑器，能够准确地为您呈现文档内容。
标题
- 整篇文档只能有一个顶级标题，并且要放在文档首行；
- 标题符号要从行首开始，位于块引用和代码块中的标题符号除外；
- 标题符号和标题文本之间要留出空格，并且只能有一个空格；
- 标题相邻的上、下行要留出空行，位于文档首行和末行时除外；
- 标题等级每次只能增加一个级别，不要越级使用；
- 标题行行尾不要使用中、英文标点符号，包括：逗号、句号、分号、冒号和感叹号；
- 整篇文档不能有内容相同的标题行；
- 整篇文档要使用统一的标题符号。
无序列表
- 无序列表相邻的上、下行要留出空行，位于文档首行和末行时除外；
- 无序列表符号与列表内容之间要留出一个空格；
- 无序列表子项符号始终缩进两个空格；
- 同级别无序列表符号的缩进始终保持一致；
- 整篇文档要使用统一的无序列表符号。
有序列表
- 有序列表相邻的上、下行要留出空行，位于文档首行和末行时除外；
- 有序列表项要从 "0." 或 "1." 开始，并且始终按照数字顺序增加序号；
- 有序列表符号与列表内容之间要留出一个空格；
- 同级别有序列表符号的缩进始终保持一致。
表格
- 表格每行开头和结尾都要放置一个管道符；
- 表格每行单元格的数量必须保持一致；
- 表格相邻的上、下行都要留出空行，位于文档首行和末行时除外。
块引用
- 块引用符号和内容之间要留出空格，并且只能有一个空格；
- 块引用行间不能有空行，但允许在空行前添加一个块引用符号。
代码和代码块
- 代码符号与文本之间不能有空格；
- 代码块要指定内部的编码语言；
- 代码块相邻的上、下行要留出空行，位于文档首行和末行时除外；
- 代码块中的命令行应省略行首的美元符号，但有输出行时除外；
- 整篇文档使用统一的代码块格式（使用缩进或者使用符号）；
- 整篇文档使用统一的代码块符号（波浪号或者反引号）。
粗体和斜体
- 不要使用整行粗体或者整行斜体文本代替标题；
- 粗体、斜体符号与文本之间不能有空格；
- 整篇文档要使用统一的粗体和斜体符号。
URL 和 email
- URL 地址或者锚点不能是空的；
- URL 文本和地址的语法顺序不能颠倒；
- 自动链接的 URL 和 email 要放入一对尖括号中；
- 自动链接的 URL 和 email 与尖括号之间不能有空格；
- 自动链接的 URL 和 email 可以包装成
代码来禁止跳转。
图片
- 应该为图片提供替代文本，当图片加载失败时显示这个文本。
分隔符
- 整篇文档应使用统一样式的水平分割符。
通用
- 不要在行末尾随无效空格，用作断行的空格除外；
- 不要使用制表符缩进，而应该使用空格缩进；
- 不要在段落间出现连续空行，位于代码块中时除外；
- 不要在单行中超过最大字符数限制（默认 80），URL 除外；
- 不要在文档中使用内联 HTML 元素，必要时除外；
- 应该使用正确的大小写书写专有名称；
- 应该使用换行符另起新行结束整篇文档。
posted on
