一直以来，我都习惯于使用 Markdown 语法来编写文档，它具有非常好的通用性和可移植性，表现简约而丰富且易于扩展。可以让人专注于写作。
本文是我长期使用 Markdown 的一些心得体会，虽然使用 Markdown 非常的简单，但是想要写出漂亮的文章也需要一些的技巧。
把文档当作是一种学习的方法
很多人对文档是存在误解的，这源于这些人并不善于写作。我们会认为写作只是为了分享我的观点，传播知识，所谓“文以载道”。确实，这是非常重要的一个目的。但，并不仅仅如此。
应该把文档、把写作当成是一种学习的方法。在学习的过程中，我们经常会遇到如下问题:
- 学会了，也用起来了。但是当别人问我的时候，我也说不清楚。
- 学了没有用起来，当要用的时候，或再次想学的时候，需要从头开始。
- 学了之后，知道要记录下来，但是不知道要写什么。
先说第一种情况，这说明你并没有真的学会，或者说你的表达能力太差了。在技术领域，大部分都是一知半解，所以也表达不清楚。所以流传着一句话：如果你能让你的孩子或者你的女朋友都能听懂，那说明你是真的学会了。所以，也有人这么说：教会别人才能证明你会了。 所以，你可以用写文档来检验自己是否真懂。
再来说第二种情况，我们经常说写代码要注释，因为时间久了自己一定是会忘记的。同样的道理，我们也说读书要做笔记，好记性不如赖笔头。去学习一项技术，我们要翻阅各种形式的资料、文档、网页、视频、书籍，散落在各个地方。下次如果要重新学起，就要重头来过，这种代价是不能承受的。 所以要学着总结、记录、整理，以备查询，温故知新 。
另外，记录文档也是一种放空自己的手段。理解了，记录下来了，也就可以忘了，保持空杯状态。
最后要说的是一句名言: 读书要把书读厚，然后要把书读薄 。这句话就可以用来回答第三个问题，不知道写什么，可以按照这句话来实践。学习一门技术，无外乎找资料和实践。最初可以找一本小册子，或者是目录提纲或者是一个思维导图。然后可以找更多的资料来丰富它，可以是网络上的资料、可以是出版的读物、可以是自己思考或者实践的成果。这就是把书读厚。接着要把读厚的书，在此读薄，这就要求我们提纲挈领，总结归纳出重要的、实用的内容加以整理、记录。经过这一个过程，我相信对知识的掌握就较为深刻。
善用基础元素
绝大部分的 Markdown 编辑器都至少支持强调( > ）、链接( alt ）、图片链接( )、加粗( 文本内容 )、斜体( 文本内容 )、有序列表( 1. 列表项 )、无序列表( *. 列表项 )、分割线( --- )行内代码块(
代码 )、 多行代码文本 (``` )以及表格(参考下方)等元素:
|列一|列二|列三|
|---|---|---|
|行一列一|行一列二|行一列三|
|行二列一|行二列二|行二列三|
要善用这些元素，表格和列表元素在很多时候可以通用，具体看排版是否简洁舒适。另外，如果是列表元素，当列表项内容超过一行的时候，或者比较多的时候，可以考虑使用空行加大列表的间距。
对于程序员来说，可能要将很多的代码的片段插入文档之内。可以使用 Markdown 的行内代码块、或者多行代码。但是有几点需要注意:
• 路径、快捷键的文本要用行内代码块包裹。
• 避免在正文中摘录大量的代码，除非是在文末的附录章节内容。
使用图床
当我们需要将图片嵌入文档的时候，可以使用  这样的格式，那么这里的 URL 怎么填写呢？
比如语雀、有道云笔记、印象笔记等软件平台，你可以使用直接粘贴截图或者拖拽图片文件到文档编辑器中，然后编辑器会自动上传图片并转换成 URL，按照 Markdown 的语法写入我们的文档。以有道为例，如下图所示:
它会转换成自定义的一串标识，作为图片的 URL。这样的形式在其他的软件上是不能够正常识别这张图片的。所以这样的文档在其他的软件平台上是不能够兼容的。另外，这样的功能，在有道云笔记上是收费的。
那么怎么办呢？我们可以使用图床，图床是一类通过上传图片，得到图片的公开的网络访问 URL 的应用。我们有两种做法:
• 第一种上传到网络上的各种公用图床上，有免费的也有收费的。
• 第二种自建图床服务。
第一种是有一些缺陷的，因为这些或免费或付费的服务，一来是由上传流量方面的限制，二来也很难保证服务的永远可用。如果某天中止服务，你的图片可能也永远找不回来了。
第二种方式是我使用的方法，可以使用云服务商提供的对象存储服务，来上传图片，得到公开的链接。推荐的云服务商有七牛云(我自己在用)、又拍云、腾讯云、百度云、京东云或者阿里云。这些云服务商都提供了对象存储的服务(OSS)，而且价格相对低廉，提供你使用不完的免费额度。
考虑文档的兼容性
但是像语雀这样的 Markdown 编辑器还支持多种更多的元素, 比如脑图、音频、文件等等元素。利用这些元素会更加丰富我们的排版和内容，但是要考虑兼容性，这些都不是标准的 Markdown 所具有的元素。除了标准的元素外，不同的编辑器支持更多的不同的元素，即使是相同的元素也有可能是不同的语法，而且这些语法有的会比较复杂。
所以，尽量少用编辑器特有的一些语法和元素，这样可以避免将来迁移的时候不必要的兼容问题。如果你仍然希望加入一些特定的元素，比如说脑图，你可以使用图片的形式插入。在其他的工具上编辑好脑图，然后插入。虽然这打破了 Markdown 沉浸式写作的体验，但是会让你的文档有着更强的兼容性，不依赖于特定的软件和平台。
基础的格式和内容编排
在写作的时候，有一些基础的格式和内容编排上的要点需要注意的。
不需要像正式的出版读物一样，开头空两格。这是因为段落与段落之间已经有明显的空行了，并不需要用开头空两格的形式去区分段落。
此外，段落之间需要有空行，但是也不能有太多的空行，一般一行足以。标题和段落之间可以有一到两行的空行。但是需要注意，有些 Markdown 的编辑器不支持多行的空行。
因经常性地分段，不要出现大段的文字。一般每个段落从几十是一两百个文字足以，不要长篇大论还不分段。
俗话说，一图胜前言，在写作内容上，尽可能地图文并茂，避免大段地文字。可以结合各种图示，来讲解内容。这样的文章更容易使人阅读、理解。
在一段文本中，标注出你觉得重要的、总结性的语句会让人觉得眼前一亮。看文章的时候也会更容易把握重点。而标注的形式可以选择加粗。不要选择斜体，因为并不明显，不要试图使用编辑器提供的颜色、以及自己在这个当中加入 HTML 或者 CSS 代码，因为不是所有的编辑器都能够识别的。
不要使用过深的层级
Markdown 的文档一般不会太长，相对于出版的图书而言，没有必要建立过多的层级，会让阅读的人失去兴趣。虽然 Markdown 的文档支持最多六级标题，但是并不建议你这么做。
之所以支持六级标题，这是因为 HTML 提供从 H1 到 H6, Markdown 最终会转成 HTML+CSS 展示在页面中。
所以，Markdown 文档最好“扁平化”，一到两级目录是比较阅读的，三级目录也是可以接受的。
另外，我也建议不要使用一级目录，如果不超过就只有两级目录，那么应该从三级目录开始使用。就如同这篇文档本身一般，只有三级目录:
因为在大多数应用中，一级标题和二级标题的字体太过于大了，相对于正文而言。而三级标题，正好能够突出标题，由不会让人觉得和正文之间有太大的差距。
写明出处
我们在文档中可能引用了很多资料，这是技术的写作中是非常正常、难以避免的。所以，最好把这些资料的出处写清楚。
如果是网页内容，可以使用链接。如果是出版读物，可以使用豆瓣平台该图书的网页。如果是某商业课程，也可以写明“某某网站某某课程”。
这样写清楚了之后，一来尊重别人的创作权，二来可以让读者通过你的引用阅读更多的内容。
念念不忘，积沙成塔
独木不成林，如果文档不成体系也会如同散沙。所以，我们需要积沙成塔，将文档编撰成册，这也是我们使用语雀这个平台的一个重要原因。可以让文档成体系的展现出来，便于创作检索。
这样讲文档成册的整理，一方面能够让你的知识成体系，避免我们迷失在知识的海洋中。另一方面也有利于团队协同，避免大家重复制造轮子，消耗过多的精力。大家相互学习创作，才能形成良好的技术氛围。