軟件工程師使用markdown寫文檔的正確姿式

軟件工程師使用markdown寫文檔的正確姿式

自從我在github上了解到markdown之後, 對markdown愈來愈愛不釋手. 從最開始的工程README, 到我的博客, 再到項目中的各類技術文檔, 我都開始使用markdown來編寫.

工程師的markdown使用場景

工程中不少須要輸入文本的地方均可以引入markdown, 以github爲列:

1. 工程README

以上爲Netflix開源項目 Hystrix 的README.
項目Logo, 項目簡介, wiki入口, 聯繫方式 包羅萬象. 這個排版很簡潔明瞭, 值得借鑑.

2. WIKI文檔

github的編輯器默認語法就是markdown, 使用wiki更能支持版本比較的功能.
而其餘主流的wiki系統也都加入了支持markdown的插件(好比xwiki, confluence).

3. 工程Issue

4. 我的博客

既然markdown都玩這麼熟了, 再用markdown寫寫博客吧.
目前主流的技術博客系統都支持了markdown編輯器編寫文章(segmentfault, oschina 甚至元老級的csdn也支持了).

工程師markdown編輯器的免費方案:

atom+插件

優勢: 使用簡單. 前端工程師藉助於atom, 編輯效率極高.

缺點: 啓動速度稍慢, 編輯框沒法與預覽框同步滾動.

Intellij+插件

優勢: 使用簡單, 對於後端工程師編輯效率高.

缺點: 啓動速度比較慢

Typora

優勢: 啓動速度快, 所見即所得, 對於小白用戶友好.

缺點: 對於編輯功能與預覽功能不能分開.

markdown使用中的小技巧

WORD轉markdown

pandoc

萬能的pandoc能夠支持多種格式文本文件相互轉換. 但格式上可能會丟失較多的樣式(好比表格語法沒有正確的轉換), 實際工做中使用較少.

saas服務

有個免費的word to markdown服務提供了word到markdown的轉換, 但網站速度訪問較慢.

typora

typora提供了一個很是簡單的word到markdown轉換方式: 在typora的預覽模式下, 全選word內容並複製進來, 內容就會自動轉成mardown格式, 這個功能作的很是棒.

markdown導出PDF文件

atom經過插件支持PDF的導出, 但不支持目錄的生成, 但功能較弱.
而typora支持導出爲PDF的功能, 且支持目錄的生成, 還支持多種主題,更爲人性化.

推廣效果

有了流行的標準markdown, 再加上便利的編輯工具typora, 在個人推廣下, 同事們逐漸接受了這種文檔編寫方式, 並開始大規模在項目中使用.