摘要：本文記錄我在使用 Markdown 過程中遇到的平臺語法和顯示差異問題，分析常見寫作平臺對於 Markdown 支援的差異以及避坑建議，文中有我的思考：技術自由和標準的取捨。
Markdown 的語法特性讓人們在寫作的過程中只需要專注於文字內容而並不需要特別在意排版，不讓思路被打斷。釋出的時候則是需要考慮讀者看到的樣式，是否美觀。
Markdown 特性
Markdown 簡介
Markdown 是一種輕量級標記語言，它允許人們使用易讀易寫的純文字格式編寫文件，然後轉換成格式豐富的 HTML 頁面。——維基百科
常用語法
下圖是網上流傳很廣的一個圖,基本語法都包含了：
為什麼流行
- 純文字，易於編輯，跨平臺支援
- 語法簡單，易學，容讀
- 流暢書寫不干擾焦點
- 方便轉換為 Html 和 PDF，適合網站寫作，成為一種網路書寫語言
- 支援 Html 特性，可以自定義複雜樣式
- 最大開源網站 Github 和最大問答社群 StackOverflow 的流行，技術人領跑
- 移動裝置普及，小尺寸閱讀體驗優化
設計哲學
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
- Windows 平臺
- 線上編輯器
- 瀏覽器外掛
推薦使用 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 程式碼：
複製程式碼對於標籤裡面的文字標記居然有不同的解釋，分歧點在轉換為 Html 是否屬性也顯示出來，常見的實現只有 multimarkdown 5.1.0 和 pandoc 2.3 是顯示出來的。
簡書的效果就是顯示的，因此猜測可能是這兩個實現的變種。
支援擴充套件效果不一致
最典型的就是表格和流程圖了。大部分的實現都支援表格的功能，通過 Babelmark 3 可以看到 6 種轉換後的 Html，如果表格裡面還使用了加粗的話更是慘不忍睹，12 種效果任君猜測在不同網站顯示，你絕對想不到的。
顯示效果
這也是個天坑，辛苦的寫好後，最終是需要面對讀者的。引起的原因無非是實現的擴充套件功能不一致以及網站的 CSS 樣式差異影響到了排版。
實現的擴充套件功能不一致
這時候就必須要關注效果了。有預覽功能那是最好的，例如 CSDN, 簡書，否則需要一次次的釋出然後檢視，修改，例如部落格園。因此選擇的工具和你釋出的平臺的相容性問題就來了，最好是都是同一個核心原始碼的變種實現。
CSS 樣式差異影響
對於表格功能是最為突出的。先看看效果比較：
因此建議不使用表格擴充套件語法，或者使用自定義css應用後轉換為圖片。
我的最佳實踐
目標就是為了一次書寫，到處釋出。以下的都是基於個人喜愛，僅供參考。
Windows 平臺下使用有道雲筆記同步素材以及沒有完成的文章。
- 寫作使用 Visual Studio Code 軟體
外掛安裝 Markdown All in One
根據需要配置想要的版本和功能支援，快捷鍵豐富，絕對是效率神器。建議寫完後開啟預覽功能檢視效果。
- 語法檢查安裝 markdownlint ，實時語法檢查對於 IDE 來說是必備的
- 圖床使用新浪微博或七牛雲
使用 Pangu-Markdown 檢查中文排版
檢查中英文混排效果是否符合通用實踐。
釋出使用 Markdown Here 轉換後檢視效果是否符合意圖再仔細檢查後貼上
- 部落格是我學習過程的輸出，希望你有所收穫。
- 有想法請留言，共同探討學習。
- 由於博主能力有限，文中可能存在描述不正確，歡迎指正、補充！
- 你也可以關注我的公眾號：ProgramLife042，名稱：風之程式人生，方便接收最新內容。
