MarkDown 文档编写说明

一、什么是 MarkDown

MarkDown 是一种轻量级的标记语言，可用于在纯文本文档中添加格式化元素。Markdown 由 John Gruber 于 2004 年创建，如今已成为世界上最受欢迎的标记语言之一。

其有以下特点：

• 专注于文字内容；
• 纯文本，易读易写，可以方便地纳入版本控制；
• 语法简单，没有什么学习成本，能轻松在码字的同时做出美观大方的排版。

二、为什么是 MarkDown

因为其排版语法简洁，让人们更多地关注内容本身而非排版。它使用易读易写的纯文本格式编写文档，可与 HTML 混编，可导出 HTML、PDF 以及本身的 .md 格式的文件。因简洁、高效、易读、易写，Markdown 被大量使用，如 Github、Wikipedia、简书等。

使用 Markdown 而不是 word 类编辑器的原因有以下：

• Markdown 无处不在。(公司选择)
• Markdown 是纯文本可移植的。(纯文本)
• Markdown 是独立于平台的。(纯文本就是好用)
• Markdown 能适应未来的变化。(简单好用)

(在编写本文的时候一开始也是用 Word 编写，因为被 Word 的标题格式弄烦了，直接转阵 md )

三、怎么用MarkDown

Markdown的工作流程很简单，首先要挑一款好用的编辑器进行写作，内容使用Markdown进行标记，然后通过编辑器的功能将文章进行渲染、发布或导出。

官网Typora下载|点击链接下载Typora

Markdown 语法学习

1. 学习基础语法

Markdown 的基础语法是指 John Gruber 最初发布的 Markdown 版本，大多数扩展语法都是基于此版本开发的，因此基础语法是需要学会的。

2. 学习扩展语法

在众多扩展语法中，GFM 无疑是目前最流行的。它扩展了包括表格、任务列表、删除线、围栏代码、Emoji 等在内的语法，功能非常全面，是笔者重点推荐学习的扩展语法。

3.学习写作规范

人们在使用 Markdown 的过程中逐渐总结出了一些最佳实践方案，并且制定了写作规范，学习这些规范可以让我们养成良好的写作习惯，避免重复“踩坑”。

另外，遵循这些规范也可以让源码（没有渲染过的文本）有更强的可读性、可移植性（一处编写，随处使用）和可维护性（有统一的认知）。

基础语法

本文简单说明如何使用 MarkDown 可以直接到官网查看使用说明 MarkDown。

标题

• 标题用＃表示
• 在行首插入#可标记出标题。
• #的个数表示了标题的等级。
• 建议在#后加一个空格。

粗体与斜体

在Markdown中，粗体 由两个 * 或两个_包裹 ，斜体 由 1 个 * 或 1 个_包裹。

段落语法

说明如下。

如果行与行之间没有空行，则会被视为同一段落。
如果行与行之间有空行，则会被视为不同的段落。

空行是指行内什么都没有，或者只有空格和制表符。

如果想在段内换行，则需要在上一行的结尾插入两个以上的空格然后按回车键。

列表

在Markdown中支持使用有序列表和无序列表，有序列表用数字序号+英文句号+空格+列表内容来标记，无序列表由*/+/-+空格+列表内容来标记。

• 这是一个无序列表
  • 这还是一个无序列表
  • 但是他的层级和第一个不一样

1. 这是一个有序列表
   1. 这还是一个有序列表
   2. 但是他的层级和第一个不一样

分割线

语法说明如下：

---

• 分隔线须使用至少 3 个以上的 * 或 - 或 _ 来标记。
• 行内不能有其他的字符。
• 可以在标记符中间加上空格。

图片

语法说明如下:

![图片昵称说明] (图片地址，本地用相对地址)

• 图片替代文字在图片无法正常显示时会比较有用，正常情况下可以为空。
• 图片地址可以是本地图片的路径也可以是网络图片的地址。
• 本地图片支持相对路径和绝对路径两种方式。

链接

Markdown中链接主要分为三种：文字链接、引用链接、网址链接。

链接文字

引用链接

行内代码与代码块

在 Markdown 中，行内代码引用使用 `包裹，语法如下：

` ` `代码块语言
	实际使用中 ` 没有空格
` ` `

四、怎么用好MarkDown

实际使用中我们会遇到各种规范性问题！
对于这些规范性问题我们要其然与其所以然

4.1语法规范建议

推荐使用 GitHub GFM 规范！

4.2 标题格式建议

推荐使用 ATX 标题 规范，最大支持 6 级标题。
即为用#的标题

4.3 空行

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

• 文件末尾空一行

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

• 标题前后各空一行

4.4 空格

• 重中之重 因为这个会被说无数次

4.4.1 中英文之间需要增加空格

正确：

在 LeanCloud 上，数据存储是围绕 AVObject 进行的。

错误：

在LeanCloud上，数据存储是围绕AVObject进行的。
在 LeanCloud上，数据存储是围绕AVObject 进行的。

完整的正确用法：

在 LeanCloud 上，数据存储是围绕 AVObject 进行的。每个 AVObject 都包含了与 JSON 兼容的 key-value 对应的数据。数据是 schema-free 的，你不需要在每个 AVObject 上提前指定存在哪些键，只要直接设定对应的 key-value 即可。

例外：「豆瓣FM」等产品名词，按照官方所定义的格式书写。`代码解释最好也加上空格

4.4.2 中文与数字之间需要增加空格

正确：

今天出去买菜花了 5000 元。

错误：

今天出去买菜花了 5000元。
今天出去买菜花了5000元。

4.4.3 数字与单位之间需要增加空格

正确：

我家的光纤入屋宽带有 10 Gbps，SSD 一共有 20 TB

错误：

我家的光纤入屋宽带有 10Gbps，SSD 一共有 20TB

例外：度 / 百分比与数字之间不需要增加空格：

正确：

今天是 233° 的高温。
新 MacBook Pro 有 15% 的 CPU 性能提升。

错误：

今天是 233 ° 的高温。
新 MacBook Pro 有 15 % 的 CPU 性能提升。

4.4.4 全角标点与其他字符之间不加空格

正确：

刚刚买了一部 iPhone，好开心！

错误：

刚刚买了一部 iPhone ，好开心！
刚刚买了一部 iPhone， 好开心！

4.5 全角和半角

个人感觉其实就是标点符号的使用规范，讲究的人可以自行去查询。

一个句子中使用什么语言就使用其对于的标点符号。
What language is used in a sentence with the appropriate punctuation marks.

4.6 名词

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

4.7 实际使用的其他问题

1. 链接之间是否需要增加空格？
   我们在使用链接的时候有时会遇到 链接名称 为英文或者中文，根据英文的格式正常情况下我们是要加空格的，可中文却不用，为了保持文章整体的规范性，个人推荐链接之间需要加空格。
2. 加粗、斜体、高亮文本前后是否需要加空格？
   个人推荐加，加粗、斜体、高亮文本会打破一个句子的规范性（观赏性），如果有空格在其中将内容分隔，个人感觉不会显得突兀。

参考（如有侵权请联系删除）

基于 Markdown 的中文文档排版规范

为什么要使用 Markdown|极客笔记 (deepinout.com)

基于 Markdown 的中文文档排版规范_markdown的设计规则-CSDN博客