最近在找一些资料的时候，看的头大，有很多很有技术含量的文章却因为格式问题让人开头就看不下去，实在可惜。这里就分享一下自己用 markdown 写文档时的一些心得，希望能对大家有所帮助。
本文会从格式和内容两大方面出发，介绍一些能让你文章更具表达性的小细节。
格式
1、不会使用空格和空行
合理使用空格和空行是 markdown 中最基础也最重要的概念。咱们首先来聊聊空格，下面这条规则推荐每个人都记住：
中英文混排、中文数字混排时，数字和英文前后要插入空格。
例如下面两个例子：
看起来十分的拥挤
云函数又称函数即服务FaaS,它和后端即服务BaaS一起,都可以称为Serverless产品,云函数在2012年被首次提出。
令人舒服的写法
云函数又称函数即服务 FaaS，它和后端即服务 BaaS 一起，都可以称为 Serverless 产品，云函数在 2012 年被首次提出。
和平时写代码一样，合理的使用空格会让你的文章可读性更高。
除了空格之外，md 中还有一个需要注意的点就是空行。在大多数 markdown 解释器中，单个换行是无效的，必须要空行（两个换行符）之后才可以正确的换行。这就导致不了解这个特性的同学写出来的文档变成了一个超长大段落。
2、不会使用格式
在网上可以看到很多很长一篇文章超长段落，而且中间还一点格式都没有，就像是一碗泡烂了的面一样让人难以下咽。下面介绍一下我平时是怎么使用常用格式的，主观性较强，如果有异议的话欢迎评论区交流：
> 粗体
粗体 算是最常见的格式了，但是常见不代表可以大范围使用，粗体是用来强调一段话，而强调必须有对比，所以不应该频繁使用。我比较推荐一个自然段中只出现一句粗体，如果没有必要的话也可以不加，总之就 宁少勿多。
> 斜体
斜体 和粗体相反，代表一段话属于次要内容，所谓次要内容就是指那些，就算是直接忽略掉也不会影响文章阅读效果的内容。
例如，写完一段后的引申内容，或者有助于理解的解释性内容，都可以用斜体标注。
在英文文章中，也有使用斜体来表明内容是引用或者其他语言的名词。但是 markdown 中有专门的引用语法，并且汉语和外语差异也很大，不存在名词混淆的情况。所以我一般都只在次要内容上上使用斜体。
> 代码块
行内代码 就不多提了，这个能用错的人还是挺少的，这里重点提一下代码块：
就是这种代码块
很多人从来不用这种东西，而 markdown 不仅 ``` 是代码块，tab 和 4 空格缩进也可以创建一个代码块，这就导致了一个让人非常崩溃的问题，如果你直接往 markdown 中贴一段代码，就会变成下面这样：
不知道你有没有裂开，反正我是裂开了。markdown 发现你代码中的缩进，所以它会把这段文本中的一部分认为是”代码“，这不仅对阅读没有帮助，反而带来了极佳的混淆效果。并且也可以看到，markdown 并不会显示两个以上的空格，所以文章里的代码缩进会直接消失。
所以作为程序员，你可以不用粗体不用斜体，但是一定要用代码块。
其实掌握了以上三种格式，已经完全足够我们写好一篇文档了。你说其他那些小格式有用么，当然有用，但不常用，这里咱也不过多赘述了，下面才是重头戏。
2、滥用格式
不要因为好看而使用某个格式，比不会使用格式更糟糕的就是滥用格式，相信很多人都见过通篇粗体或者斜体的文章，粗体还好，通篇斜体真的是看的人眼都要瞎了。格式之所以有意义，是因为它可以和普通文本产生对比。通篇特殊字体等于没有字体。
除了通篇用一个格式外，交杂使用过多不同格式也会降低阅读体验，例如下面这段文字：
大多数 Node.js 核心 API 构建于惯用的 异步事件驱动架构，其中某些类型的对象（又称触发器，
Emitter）会触发命名事件来调用函数（又称监听器，Listener）。例如，
net.Server会在每次有新连接时触发事件，fs.ReadStream会在打开文件时触发事件，stream会在数据可读时触发事件。所有能触发事件的对象都是EventEmitter类的实例。 这些对象有一个eventEmitter.on()函数，用于将一个或多个函数绑定到命名事件上。 事件的命名通常是 驼峰式的字符串，但也可以使用 任何有效的 JavaScript 属性键。
要记住，特殊的文本格式会干扰你的阅读速度，写文章和画国画一样，要讲究疏密有致。不要炫技一样地在你的文章中添加各种格式让内容显得花里胡哨。各种格式的内容混杂在一起会弱化不同格式的意义。让读者花费更多精力在分辨格式而不是内容上（最后会让读者下意识的无视你的格式）。所以请记住以下两点：
- 普通格式的内容最好占全文的三分之二，最少不要低于一半。
- 尽量避免格式嵌套，比如一个 斜体中的 粗体。
3、根据自己的喜好选择 header
很多 markdown 解释器会使用 header（就是那些一级标题、二级标题等等）来自动生成文章的目录。所以应尽量按照顺序依次选择标题级别，而不是因为某个标题的大小自己不喜欢就跳级使用标题。
内容
1、过长段落
文章让人读不下去的最大问题就是过长段落。如果一段文字越长，认真读完的人也就越少。并且，一个段落中的内容都是相互有所联系的，所以绝大多数人都会选择读完一段文字之后再停下进行思考或者进行实践，这也就导致了段落越长，读起来就会越累。
而且长段落会下意识的给人一种 “这一段内容难度比较大” 的感觉，让人更不想去读。你在各种官方技术栈的教程页面都可以看到，几乎没有超过四行的段落，因为越短的段落，给人的感觉也就越简单。
想解决长段落问题也非常简单，如果有一个超长段落，每隔两三行找一个句号，然后换行就可以了。拆开之后再加上两句粗体，文章的整体风格会立马变得清爽并且层次分明起来。
组织文章段落的核心思想就是：保持合适且均匀的信息密度，如果一段内容的信息密度太高，那么就应该对其进行拆分，如果几段内容的信息密度太低，那么就考虑是不是要合并段落，如果合并之后还是不够（就是俗称：写的太水了），那么就要思考是不是重新精简一下语言了。
2、一笔带过
写文章讲究一个有理有据，然而很多人写技术文章都像是在写笔记一样，点进去一开只有两句话，第一句说自己遇到了一个问题，第二句说执行了一个命令就好了。当你以为可以解决问题并开始实践时，却发现根本运行不了或者缺少了一段关键代码。你可能会选择评论询问作者，但是远水解不了近渴，只好转而寻找其他解决方法。过几天作者看到了你的留言，然后告诉你应该怎么做（也可能永远不会回复），然而解决问题的你已经不需要了。
真好，大家的时间都浪费了，却没有什么作用。
这种”笔记“性质的文章作者自己看了或许可以立刻想起来是怎么一回事（也有可能连自己都看不懂了，就像是写在备忘录上的一串数字 ），但是对于不了解背景环境的读者来说就是一次令人难过的阅读体验。
而现在站在作者的角度上，我认为既然选择了一个公开的地方来分享自己的文章，那么至少应该让这篇文章可以自洽，而不是缺头少尾的。这不仅让读者看起来可以更加省心，这节省了我们回复问题的时间。下面是我总结的一些原则：
- 写明背景：在文章开头用简单几句话说明文章背景、使用的技术栈以及版本等。如果是系列文章的话一定要在开头带上上一篇文章的链接。
- 写明参考：在文章最后注明参考，哪怕你自己写的很不详细，读者也可以通过你的参考来继续深入下去，并且有参考链接也方便以后的自己查阅。
3、超长代码
如果你文章里出现了一段超过十行的代码，那么就只会有不到一半的人认真读它。如果这段代码还没有注释，那这些人还要再少一半。没人喜欢读代码，无论是看文档还是维护项目。所以如果你要贴一段代码在文章里，一定记住要做下面两件事：
- 添加注释，起码对你想让读者阅读的（而不是直接拿去用）那部分代码进行注释。
- 删减无用的代码，例如一个函数里边只有中间一段代码是你文章要讲的，那么就删掉上下不相干的代码，然后写个注释说明这里进行了删减。
这个原则同样适用于超长 log。特别是 github 的 Issue 区，经常会出现铺天盖地的一大长串 log，滚轮半天都滚不完。这一长串有用么？绝大多数都是没用的，那为什么不缩减一下呢，用不了几秒钟的朋友。
4、少用截图
例如一些代码段落、或者日志，能不用截图就不用。
一是因为这种内容 markdown 本身也有对应格式可以显示出来，并且比图片加载快，小屏显示效果也比图片好。二是日后可能有复制需求，无论是你还是读者，想要复制的时候却发现这是一张图片，那可真是要难受一下的。三是如果使用了一些外链图片的话，图床万一挂了就糟糕了，没人会喜欢自己写的文章里有一张裂开的图片。
这一点不仅仅是截图，其他能用非图片形式说明的，都不应该添加配图，除非添加了配图之后能让读者更轻松的理解你的意图，或者你明确的日后肯定没有复制需求。这里要提一个特例，就是文章开头或者结束有时候会添加一张介绍图片，特别是系列文章。就像下面这种：
我对这种配图并不反对，毕竟让读者一眼就能看出来自己看的是什么相关的文章可是文字很难做到的。总结起来就是一句话，能帮助读者更好的理解和使用文章、而不是使绊子的配图就是好配图。
写在最后
上面列举了不少很小但影响阅读体验的地方，对于作者来说其实要修改的并不多。就像是代码规范一样，制定规范对代码的运行影响不大，但可以让阅读和维护代码的人更省心。
不过除了这些表面上的“样式”，核心还是要看你的内容是否有营养。一篇知识浓度很高的文章，哪怕它的格式很烂，我也会觉得这是大佬不屑于顾及这些小细节；而如果文章都是从其他地方抄过来的，哪怕你格式再漂亮，我看了开头之后也会直呼上当然后把他关掉。
下面的参考里列举了一些 markdown 相关的规范文章，如果有兴趣的话可以详细了解下。ok，以上就是本文的全部内容，如有想法欢迎评论区交流。
参考
- Markdown Lint - github
- 会用 Markdown 还不够，还得知道排版规范 - 知乎
- GitHub Flavored Markdown Spec