本文参考 Markdown 书写风格指南 来规范自己的 Markdown 书写规范;最大限度接近指南,但不完全依照指南。不过和以往相比,变化的也不多,主要是无序列表由 * 改成 -,及文件名全小写这两点吧,当然还有代码这块。

扩展名和文件名

后缀使用 .md;文件名只用小写,并用连字符 - 代替空格和其他标点符号。

空行与空格

空行

  • 不要使用连续两个空行
  • 不在文件末尾留下空行

空格

  • 英文句子之间使用一个空格
  • 中文和英文、数字之间使用一个空格
  • 中文句子之间不需要空格
  • 数字和单位之间不需要空格
  • 非闭合的 Markdown 语法,均空一格
  • 加粗、斜体和下划线不需要空格

代码

符号

除非是为了展示命令输出,否则不要在代码前加符号,而是直接在代码前标注:

Use the follwing Bash Code
echo a
echo a > file

拼写

  • 使用正确的大小写和缩写;
  • 使用已知流传更广的中译名;

无论是拼写、缩写还是中译名,如果不确定,可参考维基百科。

区块元素

标题

  • 只使用符号 #
  • 标题尽量简短
  • 避免使用相同的标题
  • 不越级使用标题
  • 不要在标题以冒号 : 和 句号 . 结尾

引用

  • 在每一行使用 > 符号

列表

  • 无序列表使用 -,而不是 *+
  • 尽量使用无序列表
  • 有序列表仅使用 1. 为序号
  • 列表前后各空一行
  • 相连的列表可以使用 <!-- --> 分离

参考