用 Markdown 寫技術文件 - 編輯工具與平台選擇

我在三年前改用 Markdown 寫部落格，著眼點在省去改樣式、設連結、調位置... 等無謂的排版工夫，全力專注在文字內容上(謎：那錯字還那麼多是為什麼？)，額外收獲是學會寫 Markdown 的技能。Markdown 無疑是當今技術寫作的主流格式，如 Github、Stackoverflow 都以它為文件排版標準，不熟悉很難在開源社群走跳，而支援 Markdown 的軟體或系統也愈來愈多，甚至有現成工具可以將 Markdown 文件轉成 HTML、PDF 或 ePub 電子書，這麼大邊的西瓜，不偎嗎？

最近有個想法，工作上一些技術文件，如操作手冊、FAQ、開發教學，過去幾乎都是用 Word 格式。有些需要長期維護更新，靠 Email 傳遞豈不每次改版要重寄一次(該寄給誰又是個好問題)，就算存在線上文件庫，使用者多半習慣下載 Word 檔回去看，不會知道文件有改版更新。

若將這些需長期維護的文件改用 Markdown 寫轉成網頁形式，即可確保讀者看到的永遠是最新版，更新時也不必主動通知。最棒的是 Markdown 文件比 Word/PDF 更容易用 Git 管理版本比對差異，什麼時侯誰改了哪裡一清二楚，更可以像 Github Pages 一樣，改完 Commit 送上版控就自動更新，確保修改都被明確記錄與備份且即時更新。若有歸檔或離線閱讀需求時，可打包部分網頁或轉成 PDF，應該也能滿足需求。

花了點時間，研究這個想法實踐的可能性。

第一個是 Markdown 編寫工具，考量要在團隊推廣，免費且擴充套件豐富的的 VSCode 是首選。VSCode 已內建 Markdown .md 檔的基本支援，經簡單測試，另外有兩個套件值得一裝：

• Paste Image
  複製圖片後在 .md 按 Ctrl-Alt-V 貼上，這個套件會將剪貼簿裡的圖片以時間為檔名存成 .png，並在游標處插入 ![](png檔名)，你如果常在抓畫面做文件，就知道這有多好用
  
• Markdown All in One
  一堆實用 Markdown 快捷鍵與小功能的集合，堪稱應有盡有懶人包，目前已累積 350 萬次下載，我想不到不安裝的理由

至於 Markdown 轉網頁的工具，考量技術文件只在內部使用，不需上傳 Github 或雲端主機，做好轉靜態 HTML 文件就好。調查目前 Markdown 轉靜態檔案工具或平台，我篩選出 Jekyll、Hugo 及 Hexo 三個主流選項進入決賽。

網路上有不少相關詳細評比，其中不乏對三者均有相當了解的前輩，在此就不斑門弄斧，直接說我的結論。

原本心中第一順位是 Jekyll，理由是它是 Github Pages 用的技術，歷經千錘百煉，功能完整及可靠度很讓人期待，但深入了解發現它必須依賴 Ruby 運作，因在 Windows 安裝 Ruby 環境較麻煩，有些人選擇用 Docker 或 Windows Subsystem for Linux 跑，我也試裝了 Docker 版還蠻順利的，但 Docker 要推廣到老爸老媽，大哥小妹，男孩女孩人人可裝，還得跟 Windows 資料夾無縫接軌明顯有困難，於是我又看了 Hugo。

一試便愛上。

Hugo 安裝超級簡單，在 Windows 平台使用 Hugo 只需下載 hugo.exe 的 ZIP 檔，解壓縮後將路徑加入 PATH 方便呼叫，這樣就好了。

只用一個 hugo.exe 檔案搞定所有事，跟 Gitea 相仿的極簡風格，完全是我的菜，我瞬間被圈粉。(至於 Hexo，它依賴 node.js 需要 npm，很快在極簡風評比中敗下陣來...)

接下來 Hugo 讓我印象深刻的是速度!

底下示範用 Hugo 建一個陽春站台：(比較囉嗦的步驟是 Hugo 新建站台時未內建樣式主題，一般會用 git clone 去 Github 拉喜歡的樣式放入 themes 目錄)

hugo new site hugo-demo
cd hugo-demo
git clone https://github.com/vividvilla/ezhil.git .\themes\ezhil
hugo new posts\first-post.md
echo theme = 'ezhil' >> config.toml
hugo server -D

此時 Hugo 預覽網站已可用瀏覽器檢視，而最讓人印象深刻的是它跟 ASP.NET 6 一樣具有 Hot Reload 功能，在 VSCode 修改 .md，存檔後一秒內即在瀏覽器看到結果：

Hugo 提供了蠻大的彈性，有自己的語法可以像 Razor 一樣自訂模版，在 HTML 中穿插動態程式，配合 CSS、JavaScript 實現各種網頁效果，並有簡單的 Section、Page Bundle 觀念可組織網站內容。像它的文件網站就是用 Hugo 建立的(原始碼在這裡)，理論上我們也能用它做到相同水準的文件網站。

試將幾份 Word 文件在 Hugo 轉成 Markdown，沒遇到太嚴重的問題，但 Hugo 有自己的概念、術語、設定、程式語法跟物件模型，坦白說，複雜度不低，要上手得花點時間，而實踐過程也有不少眉角，這些等未來有較多心得再分享。

[2022-01-06 補充] 從讀者回應，發現我忘了提 HackMD，它是一個用 Markdown 寫文件的開放式平台，尤其適合拿來寫共同筆記，另外也有付費方案提供權限控制跟私人圖檔儲存空間服務。如果因文件性質或網路存取限制不方便使用線上服務，HackMD 也有商業版 Docker 可自行安裝，甚至也有開源社群版 - HedgeDoc。由於我主要想用 Markdown 取代 Word，希望保有原本分散式作業、可離線使用的特性，而增加伺服器有維運管理的成本，故一開始就未將這類線上文件平台納入考量， 但如果要用於開源社群，HackMD 是省時省力省錢的好選擇。

I plan to replace Word with Markdown format to write tech docs, after some survey, VSCode + Hugo is my choice.