使用 Markdown 写技术博客，踩过的 6个坑
目录
- Markdown 特性
- Markdown 简介
- 常用语法
- 为什么流行
- 设计哲学
- 版本演变
- 工具支持
- 踩过了坑
- 平台帮助文档
- 语法差异
- 显示效果
- 我的最佳实践
摘要：本文记录我在使用 Markdown 过程中遇到的平台语法和显示差异问题，分析常见写作平台对于 Markdown 支持的差异以及避坑建议，文末是我的思考：技术*和标准的取舍。
Markdown 的语法特性让人们在写作的过程中只需要专注于文字内容而并不需要特别在意排版，不让思路被打断。发布的时候则是需要考虑读者看到的样式，是否美观。
Markdown 特性
Markdown 简介
Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档，然后转换成格式丰富的 HTML 页面。
——*
常用语法
下图根据 通用 Markdown 语法 截图：
为什么流行
- 纯文本，易于编辑，跨平台支持
- 语法简单，易学，容读
- 流畅书写不干扰焦点
- 方便转换为 Html 和 PDF，适合网站写作，成为一种网络书写语言
- 支持 Html 特性，可以自定义复杂样式
- 最大开源网站 Github 和最大问答社区 * 的流行，技术人领跑
- 移动设备普及，小尺寸阅读体验优化
设计哲学
Markdown is intended to be as easy-to-read and easy-to-write as is feasible. --By JOHN GRUBER
易读易写，很朴素的理念。专注写作，大道至简。
版本演变
工具支持
Markdown 是一种用来写作的轻量级「标记语言」，满足大家一处写作处处使用的梦想。
目前支持 Markdown 语法的工具和产品很多，下面列举一些常见的，各人根据习惯选取，有好的推荐也请留言告知：
- 支持网站
- GitHub
- *
- ****
- OpenStreetMap
- 博客园
- 简书
- 笔记工具
- 印象笔记
- 有道云笔记
- 为知笔记
- 编辑器
- Windows 平台
- Typora
- MarkdownPad
- MarkPad
- VS Code
- Linux 平台
- ReText
- Haroopad
- VS Code
- Mac 平台
- Bear
- Mou
- MacDown
- Windows 平台
- 在线编辑器
- stackedit.io
- Markable.in
- Dillinger.io
- maxiang.io
- https://mermaidjs.github.io/mermaid-live-editor/
- 浏览器插件
- MaDe (Chrome)
- Mardown Here!
推荐使用 Visual Studio Code，作为一个全宇宙最强编辑器的延伸，插件丰富，你值得拥有。什么，不会配置，太复杂了，想要随处可用，地铁也码字？有道云笔记走起。
踩过了坑
开源本没有路，走的人多了，也就成了路，踩的坑多了你也就放弃了。
——开源项目真实写照。
平台帮助文档
必须放在第一位，没有详尽帮助文档的工具，请放弃，否则掉坑怎么都爬不出来。工具栏+预览基本都是标配，这个就没什么好说的了，想看语法就逐个点击一下就支持这个编辑器支持的基本语法，熟悉了就可以抛弃这种低效率的方式，解放拿鼠标的手。
这方面国内做的最好的是 **** 的编辑器。进来就是一篇例子为正文，双栏支持预览，右上角有明显问号帮助图标，点击后有分主题的帮小例子。
其次就是有道云笔记了，界面双栏预览，右上角问号帮助点击后跳转到管网帮助文档，初阶和高阶两篇，足够入门。遗憾的是文中参学习的链接已经失效，没有及时更新。
最差就是简书和博客园了。感受一下：
简书至今没有找到明显的帮助，也找不到具体实现依赖，通过粘贴几段示例验证应该是 CommonMark and Github Flavored Markdown。
语法差异
语法差异其实就是看支持的是 Markdown 的哪一种实现，以及对应的配置选择。好消息就是，通用的格式 CommonMark 里面基础的标记是都支持的，只是单纯文字和图片几乎是随处可用，样式一致。
有一个专门的开源项目 Babelmark 3 是不同 Markdown 实现结果归类，目前收集了 33 个版本
目前大部分编辑工具都可以选择实现的方式，是否开启样式。
网站上则是只能遵守固定的规则去修改了。
列表出现空行效果问题
这是 Markdown 都存在的问题，来自定义列表时候没有严格定义这种行为处理。具体可以参见 CommonMark Spec V0.28。Markdown 常见的不小心加了空行会出现什么事情呢？
导致出现不同转换 Html 的样式。在转换列表里是否使用、
和、
出现了分歧。
图片插入标记属性展示问题
对月于下面这段 Markdown 代码：
对于标签里面的文字标记居然有不同的解释，分歧点在转换为 Html 是否属性也显示出来，常见的实现只有 multimarkdown 5.1.0 和 pandoc 2.3 是显示出来的。
简书的效果就是显示的，因此猜测可能是这两个实现的变种。
支持扩展效果不一致
最典型的就是表格和流程图了。大部分的实现都支持表格的功能，通过 Babelmark 3 可以看到 6 种转换后的 Html，如果表格里面还使用了加粗的话更是惨不忍睹，12 种效果任君猜测在不同网站显示。
显示效果
这也是个天坑，辛苦的写好后，最终是需要面对读者的。引起的原因无非是实现的扩展功能不一致以及网站的 CSS 样式差异影响到了排版。
实现的扩展功能不一致
这时候就必须要关注效果了。有预览功能那是最好的，例如 ****, 简书，否则需要一次次的发布然后查看，修改，例如博客园。因此选择的工具和你发布的平台的兼容性问题就来了，最好是都是同一个核心源码的变种实现。
CSS 样式差异影响
对于表格功能是最为突出的。先看看效果比较：
因此建议不使用表格扩展语法，或者转换为图片。
我的最佳实践
目标就是为了一次书写，到处发布。以下的都是基于个人喜爱，仅供参考。
Windows 平台下使用有道云笔记同步素材以及没有完成的文章。
- 写作使用 Visual Studio Code 软件
-
插件安装 Markdown All in One
根据需要配置想要的版本和功能支持，快捷键丰富，绝对是效率神奇。建议写完后打开预览功能查看效果
-
使用 Pangu-Markdown
Extension 检查中英文混排效果是否符合常规实践。
发布使用 Markdown Here! 转换后查看效果是否符合意图再仔细检查后发布
感兴趣交流可以留言，共同探讨学习，限于作者水平有限，理解不到位，有错误的地方望不吝赐教，感谢!
你也可以关注公众号：ProgramLife042，公众号名称：风之程序人生。查看更多最新内容。