學習 Markdown：軟件開發人員的寫作工具

如果您是一名軟件工程師，您可能已經花費了大量時間來優化您的環境以提高您的工作效率。 你有你最喜歡的 IDE。 你有你最喜歡的調試器。 你有你最喜歡的性能監控工具。 但是您編寫文檔、手冊和報告的工具呢？ 畢竟，寫作確實會佔用你大量的時間，不是嗎？ 確實，是時候認真對待你的寫作工具了。

請記住，您是技術人員，因此所見即所得的編輯器可能是您的最佳選擇，也可能不是。 您不一定想要（甚至不喜歡！）導航菜單、工具欄和功能區來格式化您的文本。

那麼，如果相反，您可以輕鬆地將所有格式樣式作為簡單的內聯語法添加到文本中以生成完全格式化的文本呢？

嗯，事實上，你可以。 這就是 Markdown，這就是本教程的全部內容。

當更多是更少...

編寫文字處理軟件是為了滿足極其廣泛的用戶和用例，因此需要提供各種功能。 但很明顯，只有一小部分功能可能與每個用戶相關。 對於大多數只想編寫文檔（而不需要設計營銷手冊或海報）的用戶來說，許多可用選項中的一小部分是相關的。

事實上，微軟幾年前就清楚地意識到了這一點，當時他們將 Microsoft Word 的用戶界面重新設計為不同的功能組，他們稱之為“功能區”。 然而有趣的是，大多數用戶會告訴您，他們發現新界面比其前身更令人困惑和難以導航。

事實上，在易用性和生產力方面，有時更多可能會更少。

……當少即是多

面對現實，你是一名軟件工程師，而不是平面設計師。 您只想編寫該手冊、技術文檔或報告，然後完成它。 您會非常高興並滿足於一些基本的格式化功能，如標題、項目符號或編號列表以及代碼塊。 而且，哦，是的，一些字體格式（粗體、斜體等）也會有所幫助。 就是這樣。 （伙計，如果你甚至可以在 vi 中做到這一點，那真是太棒了！）

輸入降價。

什麼是降價？

John Gruber（來自技術大師和互聯網活動家 Aaron Swartz 的大量貢獻）於 2004 年創建了 Markdown 語言，其目標是讓人們“使用易於閱讀、易於編寫的純文本格式進行書寫，並且可以選擇將其轉換為結構上有效的 XHTML（或 HTML）”。

Markdown 被設計成可以按原樣閱讀，看起來不像是用標籤或格式說明標記的（不像用 RTF 或 HTML 等標記語言格式化的文本，其原始格式既難以創作又難以閱讀）。

Markdown 允許您使用易於閱讀、易於編寫的純文本格式進行編寫，然後可以將其轉換為結構上有效的 HTML。 所以，完全準確地說，Markdown 真的是兩件事：

1. 純文本格式語法
2. 一種將純文本格式轉換為 HTML 的軟件工具（其第一個版本是用 Perl 編寫的）。

Markdown 包含了一些簡單、相當直觀且易於使用的語法約定。 特別是對於作為一名軟件工程師的你——他們不會因為需要學習和使用這些基本的語法約定而感到厭煩——Markdown 確實可以成為你想寫的東西和寫出來的東西之間阻力最小的路徑。

學習 Markdown：入門

Markdown 很容易學習。 超級容易。 您可以在五分鐘內學習基礎知識，它會很快成為第二天性。 而且——就像 CSS 和 CSS 預處理器之間的關係一樣——你可以盡可能少地使用或盡可能多地使用。

如果您習慣於任何類型的純文本書寫約定，那麼您可能已經熟悉一些降價約定，例如在句子開頭使用數字或破折號來創建列表，在單詞周圍使用星號表示強調等等在。 因此，例如，如果您想以斜體顯示某些內容，只需將其包裹在*this*之類的星號中（而不是像<span>this</span>之類的更笨重的 HTML 語法）。

同樣，您可以通過簡單地在行中添加“#”前綴來指定 H1 標題（例如， # Section Heading ，而不是<h1>Section Heading</h1> ）。

學習 Markdown 的另一個重要用途，尤其是對我們軟件工程師而言，就是將它用於源代碼存儲庫的文檔。 大多數 repos 包含一個README.md文件（ .md是 Markdown 文件的標準擴展名）。 例如，Github 有自己的“Github 風格的 Markdown”，它專門為開發文檔添加了額外的功能。 與必須用 HTML 編寫此文檔相比，這無疑可以節省時間。

作為一個簡單的示例，假設您想在文檔中包含以下代碼段：

<h2 style=color:#3863a0;font-size:1.5em;font-weight:600;margin-top:2em;margin-bottom:1em;line-height:1.3em;>啟動插件</h2>

使用 jQuery 在容器上啟動pluginName ，如下所示：

$(function() { $('#container').pluginName(); }); 使用我們容器的 ID，我們可以使用 jQuery 方法.pluginName()來啟動pluginName 。

這是在 HTML 與 Markdown 中如何完成此操作的比較：

為了進一步幫助入門，有許多在線 Markdown 教程可以幫助您快速入門，包括 John Gruber（Markdown 的創建者）的 Markdown 概述以及在線 Markdown 教程。

Markdown 解析器和工具

使用 Markdown 編寫文章後，您將需要一個應用程序來將語法解析為 HTML。 有一些很棒的免費的，包括：

• StackEdit - 基於瀏覽器的 Markdown 編輯器，具有一些與 Google Drive 和 Dropbox 等流行服務同步的選項
• Online Kramdown Editor - 另一個基於瀏覽器的 Markdown 編輯器，界面極其簡單
• Mou - 我遇到過的最好的基於 Mac 的 Markdown 編寫器，是開發人員的極客選擇； 大量功能和免費（在測試版中） [這是我用來寫這篇文章的內容]
• MarkdownPad - 適用於 Windows 的出色 Markdown 編輯器
• Texts - 一個不錯的跨平台（Mac 和 Windows）編輯器； 導出為多種格式，例如 PDF、.doc 和 ePub

一些主要平台已經在其編輯器中採用（或至少允許）Markdown 使用，供那些希望使用它的人使用。 對於 WordPress、Evernote 和 Google Docs 等其他工具，本地支持（在撰寫本文時）尚未推出，但第三方已經引入了自定義解決方案。 這些包括：

• 流行的新博客平台 Ghost 為了簡化在線寫作，使用 Markdown 作為其內容編輯器。
• 對於 WordPress，Jetpack 插件現在正式支持 Markdown，如果您使用該插件，您可以在設置 > 討論下啟用它。 或者您可以使用像 WP-Markdown 這樣的插件，它將您的 post markdown 內容轉換為 HTML，並在您需要編輯它時返回 Markdown。
• 對於 Evernote，一些 Markdown 應用程序，如在線編輯器 Markable 或 Mac 編輯器 Byword 允許直接導出和發佈到筆記。 或者，如果您更喜歡直接使用 Evernote 網絡應用程序，您可以使用名為 Markdown Here 的瀏覽器擴展程序，只需單擊工具欄按鈕，即可將寫入 Markdown 的選定筆記轉換為格式化文本。
• Google Docs 本身還不支持 Markdown，但一些編輯器（例如 StackEdit）將直接與 Drive 導出/同步。

缺點

當然，非常簡單也有局限性。 正如我已經解釋過的，Markdown 不是為需要高級格式化功能的複雜文字處理任務而編寫的。 如果這就是您所需要的，那麼 Markdown 不是正確的工具。

但是對於需要編寫用戶手冊或技術文檔或技術報告的開發人員，Markdown 在簡單性和您需要的功能之間提供了近乎完美的平衡。

也許最大的缺點——尤其是對於我們這些熱衷於變更控制的工程師來說——是無法在 Markdown 中協同工作並跟踪變更（不過，一個值得注意的例外是 Google Docs 的 StackEdit 插件）。 當然，只要付出最少的努力，就可以通過 git 存儲庫簡單地協作處理 Markdown 文檔，從而獲得通常需要的所有變更跟踪和協作。

結論

那麼所有人都在學習 Markdown 嗎？ 當然不是。 從來沒有一種工具是。

但如果你是一名軟件工程師，它很可能正是你一直在尋找的寫作工具。 因此，如果您還沒有嘗試過，那麼您真的應該試一試。