為什麼不應該使用Markdown來寫文檔
Python部落(python.freelycode.com)組織翻譯，禁止轉載，歡迎轉發。
Markdown
是互聯網上最普遍使用的輕量級標記語言。對於寫博客和評論這類的任務，用
Markdown
很棒。不過最近技術社區的人員開始用它來寫文檔。
下面我列出一些反對使用
Markdown的觀點，希望能幫助你決定是否適合使用
Markdown。如果你在考慮使用
Markdown，我希望你也可以關注下
Asciidoctor和
Sphinx，我發現用它們寫文檔更好。
人們選擇
Markdown是因為它可以很簡單的處理一些基本任務。開發者選擇它是因為
GitHub支持它，儘管
GitHub支持
9種不同的標記語言，包括
Asciidoc和
reStructuredText。但是當文檔從幾頁逐漸增長到大的文檔集，
Markdown很快就崩潰並成為累贅。下面是這種情況發生的原因。
缺乏一個標準
最初，
Markdown
是由
John Gruber寫的
initial implementation來定義，但並未明確規定行為規範。
隨著
Markdown越來越流行，越來越多的站點開始支持
Markdown的實現，這些站點是用其它語言寫成的，因此產生了更多的
Markdown實現。所有這些實現有輕微差別，但都達不到令人接受的程度。
比如有些實現要求開頭有一個空格，但另外的一些不做要求：
還有一些小問題使得
Markdown很難在不同的站點和版本之間移植
在過去的幾年裡，
Commonmark已經發展成標準化的
Markdown
。這很好，應該解決很多問題，但是卻沒人採用它。
風格
Markdown
缺乏採用的主要原因是這些年來其一直在變化。起初，
Markdown功能很有限，每當有流行的工具在
Markdown
上實現的時候，都會有一個特定的風格。聽起來不錯
，是吧？問題是每一個工具都形成了不同的風格，甚至連實現相似任務的工具都有不同的語法。
舉個例子，在
Markdown Extra中代碼塊是下面這種樣式：
這將
python類應用於輸出的
HTML
塊
然而，同樣的情況在
GitHub Flavored Markdown中是這樣的：
這會將語法高亮顯示應用於實際呈現的
HTML輸出。
相似的概念，不同的語法，但都是
Markdown。
缺乏擴展
其它的標記語言，可以對其進行擴展以提供需要的功能。它們在語法上有增添新功能同時又不會違反初始規範的機制。
比如
reStructuredText，具有內嵌和塊級別的標記：
可以了解更多關於
rfc，
class和
contents的概念。
作為一個使用
rST或
Asciidoctor的開發者，我可以以一種簡單，可插入的方式增添新的標記。
我不必改變語言的解析方式，而且我還可以通過標準擴展機制向其它用戶分享那些新功能。
在不同的版本間進行移植這些功能，用
Markdown可辦不到。
注意：
CommonMark正在開發可擴展性的語法，但還沒有實現。
缺乏語義化
儘管很多人添加了很多擴展，但都不夠語義化。這意味著不能寫
Class或
Warning，只能寫文本。因此很多人直接將
HTML嵌入到
Markdown中：
而在
reStructuredText中，你可以寫成：
這在
HTML,PDF，甚至任何創建的輸出格式中都可以合適的顯示為一個
Warning.
語義化標記可以將所寫的文字與它們的顯示方式完全分開。
缺乏語義化將導致問題，原因如下：
現在
Markdown依賴於顯示中的特定
CSS類，這意味著編寫者必須考慮如何設計頁面。
內容不可再移植到其他輸出格式（
PDF等）。
轉換到其他標記工具和頁面設計變得更加困難。
注意：
在我的博文
Semantic Meaning in Authoring Documentation中有關於語義化更詳細的介紹。
鎖定和缺乏可移植性
風格的多種多樣及缺乏語義化導致鎖定。一旦創建了大的
Markdown文檔集，就很難將它們遷移到另一個工具上，即使該工具宣稱支持
Markdown！自定義的
HTML類和奇怪風格的擴展組成的文檔集，除了在當前的工具和設計外，在其它地方都行不通。
同時也無法輕易將
Markdown遷移到其他標記語言（
Asciidoc或
RST），因為
Pandoc和其他轉換工具不支持您風格的擴展。
很多人選擇
Markdown是因為他們認為他們可以在稍後遷移到其他工具或其它標記語言。
Markdown
絕對是最低的共同標準，除非文檔集足夠小，否則你所需要的東西都不在基本語法中。
任何有意義的文檔都需要擴展，而一旦使用
Markdown各種各樣風格的擴展，你將失去所有可移植性的優勢。
結論
我認為
CommonMark是向前邁出的一大步，如果它被更廣泛地使用，並且增加對擴展的支持，我會全心全意地推薦它作為解決這個問題的方法。我不能擁護
Markdown目前的生態系統，並且我認為它很大程度上阻止了人們使文檔變得更好。
我希望我們可以開始推進更加標準化的語言集合，包括
CommonMark，
reStructuredText和
Asciidoc，在我們使用的工具套件中全面支持他們。目前，
Sphinx和
Asciidoctor是很好的替代品。它們語音內部內置了更多的擴展，並且含有用於構建當今文檔更完整的工具。
Markdown
更像是一個概念，而不是實現。
它通常意味著「在看起來與
Markdown類似的語言上的一組互不兼容的擴展」。
當創建大的文檔集時，它顯然不是正確的工具。
披露：我從事的一款產品，
Read the Docs，是基於
Sphinx的，所以我的觀點可能有偏頗。
英文原文：http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
譯者：Chris
※如果你也用Win10，真的請備份！
※【限量閃購】《Python大戰機器學習》僅售40元，只有3本，先到先得。
TAG:Python程序員 |