使用 Markdown 写技术博客，我踩过的 6个坑

摘要：本文记录我在使用 Markdown 过程当中遇到的平台语法和显示差别问题，分析常见写做平台对于 Markdown 支持的差别以及避坑建议，文中有个人思考：技术自由和标准的取舍。

Markdown 的语法特性让人们在写做的过程当中只须要专一于文字内容而并不须要特别在乎排版，不让思路被打断。发布的时候则是须要考虑读者看到的样式，是否美观。

Markdown 特性

Markdown 简介

Markdown 是一种轻量级标记语言，它容许人们使用易读易写的纯文本格式编写文档，而后转换成格式丰富的 HTML 页面。——维基百科

经常使用语法

下图是网上流传很广的一个图,基本语法都包含了：

为何流行

1. 纯文本，易于编辑，跨平台支持
2. 语法简单，易学，容读
3. 流畅书写不干扰焦点
4. 方便转换为 Html 和 PDF，适合网站写做，成为一种网络书写语言
5. 支持 Html 特性，能够自定义复杂样式
6. 最大开源网站 Github 和最大问答社区 StackOverflow 的流行，技术人领跑
7. 移动设备普及，小尺寸阅读体验优化

设计哲学

Markdown is intended to be as easy-to-read and easy-to-write as is feasible. — By JOHN GRUBER

易读易写，很朴素的理念。专一写做，大道至简。

工具支持

Markdown 是一种用来写做的轻量级「标记语言」，知足你们一处写做到处使用的梦想。
目前支持 Markdown 语法的工具和产品不少，下面列举一些常见的，各人根据习惯选取，有好的推荐也请留言告知：

• 支持网站
  • GitHub
  • StackOverflow
  • CSDN
  • OpenStreetMap
  • 博客园
  • 简书
  • 知乎
  • 掘金
• 笔记工具
  • 印象笔记
  • 有道云笔记
  • 为知笔记
• 编辑器
  • Windows 平台
    • Typora
    • MarkdownPad
    • MarkPad
    • VS Code
  • Linux 平台
    • ReText
    • Haroopad
    • VS Code
  • Mac 平台
    • Bear
    • Mou
    • MacDown
• 在线编辑器
  • stackedit.io
  • Markable.in
  • Dillinger.io
  • maxiang.io
  • mermaid
• 浏览器插件
  • Markdown Here

推荐使用 Visual Studio Code，做为一个全宇宙最强编辑器的延伸，插件丰富，你值得拥有。什么，不会配置，太复杂了，想要随处可用，地铁也码字？有道云笔记走起。

版本演变

如今 Markdown 发展红红火火，缺点也是显而易见的，相信用过一段时间的人都有体会，槽点满满。

没有统一标准

Gruber has argued that complete standardization would be mistaken: “Different sites (and people) have different needs. No one syntax would make all happy.”

创始人对于这个问题的回应，我是不认同的。扩展性和标准并不冲突，自由也是在必定的框架内。这也就致使了第一个 Perl 版本后各类语言版本都根据必定的规则更严格的扩展了 Markdown 的语法，产生了层出不穷的工具。

编辑器和语法

选择了一个顺手的编辑器，也就等于选择了一种 Markdown 语法实现。所以有特别需求的，例如流程图，生成目录，复杂表格支持，大量数学公式展现，特别须要了解编辑器支持的状况以及展现发布的站点是否支持。

版本演进

主要版本的信息请参考我写的另一篇文章（连接）思惟导图以下：

标准化

2016年3月 RFC 7763 提出将增长一种 MIME type 类型 text/markdown ,而 RFC 7764 则讨论了几种常见类型的Markdown 归入到标准化： MultiMarkdown, GitHub Flavored Markdown (GFM), Pandoc, CommonMark, and Markdown Extra 。具体参考连接 Markdown Variants，这是一个可喜的进步。

拥抱变化

开源的理念：容许用户经过添加扩展来提供所需的特性。可是没有一个标准，只是一个概念，不拥抱变化，那就只有淘汰了。没有哪种技术是一开始就完善的，都是通过不断的版本迭代，服务于开发者。这也是另一个角度看后面为什么那么多变种语法都遵循了 CommonMark，包括你们熟知的 GitHub Flavored Markdown (GFM) 。

踩过的坑

开源本没有路，走的人多了，也就成了路，踩的坑多了你也就放弃了。
——开源项目真实写照。

平台帮助文档

必须放在第一位，没有详尽帮助文档的工具，请放弃，不然掉坑怎么都爬不出来。工具栏+预览基本都是标配，这个就没什么好说的了，想看语法就逐个点击一下就支持这个编辑器支持的基本语法，熟悉了就能够抛弃这种低效率的方式，解放拿鼠标的手。

这方面国内作的最好的是 CSDN 的编辑器。进来就是一篇例子为正文，双栏支持预览，右上角有明显问号帮助图标，点击后有分主题的帮小例子。

其次就是有道云笔记了，界面双栏预览，右上角问号帮助点击后跳转到管网帮助文档，初阶和高阶两篇，足够入门。遗憾的是文中参学习的连接已经失效，没有及时更新。

掘金文档通常，高级的用法没有说明，指向的连接已经失效，找不到是基于哪种变种开发的，尝试了，发现公式也是支持的，脚注不支持，基本肯定是相似 Pandoc，但不是 Markdown Extra 。

最差就是简书和博客园了。感觉一下，博客园：虽然能够自定义丰富的 CSS 和 模板，可是后台也太丑陋了。

简书至今没有找到明显的帮助，也找不到具体实现依赖，经过粘贴几段示例验证应该是 CommonMark and Github Flavored Markdown。

语法差别

语法差别其实就是看支持的是 Markdown 的哪种实现，以及对应的配置选择。好消息就是，通用的格式 CommonMark 里面基础的标记是都支持的，只是单纯文字和图片几乎是随处可用，样式一致。

有一个专门的开源项目 Babelmark 3 是不一样 Markdown 实现结果归类，目前收集了 33 个版本

目前大部分编辑工具均可以选择实现的方式，是否开启样式。
网站上则是只能遵照固定的规则去修改了。

列表出现空行效果问题

这是 Markdown 都存在的问题，来自定义列表时候没有严格定义这种行为处理。具体能够参见 CommonMark Spec V0.28。Markdown 常见的不当心加了空行会出现什么事情呢？
致使出现不一样转换 Html 的样式。不一样解析器实如今转换列表里是否使用段落添加<p> 或  <br> 出现了分歧。没有对错之分，只是符合你的需求就好，所以说最终发布须要仔细阅读调整一下颇有必要，趟过一次坑基本一眼就能够找到问题。

图片插入标记属性展现问题

对于下面这段 Markdown 代码：

![图片标记显示](https://ws1.sinaimg.cn/large/66cf5bc0ly1fve6pmxkfrj20u605uwet.jpg)
复制代码

对于标签里面的文字标记竟然有不一样的解释，分歧点在转换为 Html 是否属性也显示出来，常见的实现只有 multimarkdown 5.1.0 和 pandoc 2.3 是显示出来的。

简书的效果就是显示的，所以猜想多是这两个实现的变种。

支持扩展效果不一致

最典型的就是表格和流程图了。大部分的实现都支持表格的功能，经过 Babelmark 3 能够看到 6 种转换后的 Html，若是表格里面还使用了加粗的话更是惨不忍睹，12 种效果任君猜想在不一样网站显示，你绝对想不到的。

显示效果

这也是个天坑，辛苦的写好后，最终是须要面对读者的。引发的缘由无非是实现的扩展功能不一致以及网站的 CSS 样式差别影响到了排版。

实现的扩展功能不一致

这时候就必需要关注效果了。有预览功能那是最好的，例如 CSDN, 简书，不然须要一次次的发布而后查看，修改，例如博客园。所以选择的工具和你发布的平台的兼容性问题就来了，最好是都是同一个核心源码的变种实现。

CSS 样式差别影响

对于表格功能是最为突出的。先看看效果比较：

所以建议不使用表格扩展语法，或者使用自定义css应用后转换为图片。

个人最佳实践

目标就是为了一次书写，处处发布。如下的都是基于我的喜好，仅供参考。
Windows 平台下使用有道云笔记同步素材以及没有完成的文章。

1. 写做使用 Visual Studio Code 软件

2. 插件安装 Markdown All in One

   根据须要配置想要的版本和功能支持，快捷键丰富，绝对是效率神器。建议写完后打开预览功能查看效果。

3. 语法检查安装 markdownlint ，实时语法检查对于 IDE 来讲是必备的
4. 图床使用新浪微博或七牛云

5. 使用 Pangu-Markdown 检查中文排版

   检查中英文混排效果是否符合通用实践。

6. 发布使用 Markdown Here 转换后查看效果是否符合意图再仔细检查后粘贴
   
   

1. 博客是我学习过程的输出，但愿你有所收获。
2. 有想法请留言，共同探讨学习。
3. 因为博主能力有限，文中可能存在描述不正确，欢迎指正、补充！
4. 你也能够关注个人公众号：ProgramLife042，名称：风之程序人生，方便接收最新内容。
   

​