个人书写规范，Markdown 风格指南

 

2018-06-29

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

扩展名和文件名

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

空行与空格

空行

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

空格

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

代码

符号

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

Terminal window
1
Use the follwing Bash Code
2
echo a
3
echo a > file

拼写

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

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

区块元素

标题

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

引用

  • 在每一行使用 > 符号

列表

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

参考

# Markdown