markdown书写风格(整理后)

markdown书写风格(整理后)

Markdown 是由 John Gruber 于 2004 年创建的一种文本标记语言，目的是让人们使用“直观的、便于阅读的纯文本格式”书写文档。

1、布局上的规范

标题

标题分为四级。
一级标题：文章的标题
二级标题：文章主要部分的大标题
三级标题：二级标题下面一级的小标题
四级标题：三级标题下面某一方面的小标题

• （1）Github issues 中填写的标题为 h1, 因此在正文中不应再出现一级标题。
• （2）层级混乱，结构不明，不可跨级别使用标题（不使用非以上四级的标题）。
• （3）圆括号应使用中文输入法进行输出。
• （4）参考链接应设为二级标题。
• 建议：如果三级标题下有并列性的内容，建议只使用项目列表（Item list）。

段落

一个段落只能有一个主题，或一个中心句子。
段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为核心句服务。
一个段落的长度不能超过七行，最佳段落长度小于等于四行。
段落的句子语气要使用陈述和肯定语气，避免使用感叹语气。
段落之间使用一个空行隔开。
段落开头不要留出空白字符。

• （1）段与段之间应该使用空行分隔，保持间隔有助于阅读美观。
• （2）段落开头不使用缩进字符填充，与英语文章统一，也便于输入。
• （3）段首中心句与段落其他句子的联系，由总到分。
• （4）段落长度最好小于等于四行。
• （5）文章结尾（完）字宣告文章结束

引用

• 全篇转载，在全文开头显著位置注明作者和出处，并链接至原文。
• 引用第三方内容时，应注明出处。
• 使用外部图片时，必须在图片下方或文末标明来源。

2、元素上的规范

2.1 标题

GitHub GFM 规范支持 ATX 标题 和 Setext 标题 规范，推荐使用 ATX 标题 规范，最大支持 6 级标题。

• 推荐使用 ATX 标题 规范

2.2 空行

• 不要有多余的空行

  在 Markdown 文本中，想要做到渲染后 真换行 通常是使用两个空格加一个回车换行符（Unix 下只有回车 CR），或者粗暴地空一行，但是 请不要连续空两行及以上。

• 文件末尾空一行

  强烈建议文件末尾空一行，大多数格式检查工具都会检查文件末尾的空行。文件末尾增加空行的可能原因是为了方便进行文件拼接处理。

• 标题前后各空一行

2.3 空格

• 中英文之间需要增加空格
• 中文与数字之间需要增加空格
• 数字与单位之间需要增加空格
• 全角标点与其他字符之间不加空格

2.4 标点符号

• （1）中文语句的结尾处应该用全角句号（。）。
• （2）注意避免”一逗到底“,合理使用句号分隔段落意思。
• （3）补充说明时，使用全角圆括号（（）），括号前后不加空格。
• （4）所有标点符号必须使用中文输入法进行输出。
• 不重复使用标点符号

2.5 全角和半角

• 使用全角中文标点
• 数字使用半角字符
• 遇到完整的英文整句、特殊名词，其内容使用半角标点

2.6 名词

• 专有名词使用正确的大小写
• 不要使用不地道的缩写

2.7 其它

• 链接之间增加空格

• 加粗、斜体、高亮文本前后加空格

  建议在 加粗、斜体、高亮文本 前后加空格，否则某种情况会出现格式解析失败。

  建议用法：

  修复了一个 内存泄露 问题，该问题由 someone 在 版本 v0.1.1 中引入。
  测试文本，这是测试。

• 列表缩进

  建议使用 4 个空格进行文本缩进，尤其是遇到有序列表或者无序列表的时候。另外，在使用无序列表或者有序列表的时候，建议在上下级之间空一行，同级之间可以不空行。

• / 的使用

  建议 / 字符前后留空格，充当路径描述符的时候除外。

• 简体中文使用直角引号

  用法：

  「老师，『有条不紊』的『紊』是什么意思？」

  对比用法：

  “老师，‘有条不紊’的‘紊’是什么意思？”