使用 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，名稱：風之程序人生，方便接收最新內容。
   

​