摘要

本文旨在說(shuō)服工程師們，尤其是敏捷團(tuán)隊(duì)的成員,，在撰寫(xiě)過(guò)程文檔時(shí),，放棄傳統(tǒng)方式，嘗試使用：1,、Markdown撰寫(xiě),；2、SVN/Git版本管理,；3,、HttpServer排版；—— 3合1的新方式,。

本文也描述了相關(guān)的技術(shù)要素：如何不再打開(kāi)Office或WPS,，只需普通的記事本，一樣寫(xiě)出漂亮,、易讀的文章,；如何搭建一套Markdown->html的生成、發(fā)布,、和訪問(wèn)系統(tǒng),；如何使用瀏覽器快捷、永久的訪問(wèn)文檔……

關(guān)鍵詞

文檔代碼化 markdown toc headeranchor

目錄

• 理論篇

  • 文檔的傳統(tǒng)方式

  • 文檔的新方式

  • 文檔的代碼化

• 實(shí)現(xiàn)篇

  • 標(biāo)記語(yǔ)言與Markdown

    • Markdwon工具軟件

    • Markdown基礎(chǔ)

  • 工作流

  • 一些技術(shù)細(xì)節(jié)

• 附錄

  • SublimeText的基本使用

    
    

    
    

    
    

理論篇

項(xiàng)目中的文檔有很多種：需求/用戶故事,、方案設(shè)計(jì),、詳細(xì)設(shè)計(jì)、接口說(shuō)明,、測(cè)試報(bào)告…… 以前的軟件工程理論將這些文檔分?jǐn)偟讲煌慕巧砩?；現(xiàn)代的敏捷理論強(qiáng)調(diào)工作的軟件高于詳盡的文檔，講求文檔的簡(jiǎn)單有效和角色的互相滲透合并,。本文不論兩者的優(yōu)劣,，只想探討一下如何讓寫(xiě)文檔變的更方便、更愉悅這個(gè)話題,，竊以為應(yīng)該是對(duì)兩派同學(xué)都是有益處吧,。

文檔的傳統(tǒng)方式

回顧一下我們文檔撰寫(xiě)、分發(fā),、閱讀,、更新的傳統(tǒng)方式：

• 找到文檔模板：例如是word/Excel/PowerPoint模版。大公司里不要小瞧了找模板的困難,，尤其是寫(xiě)跨部門(mén),、跨團(tuán)隊(duì)的文檔,，要找別人的模版時(shí),。找不對(duì)的話提交系統(tǒng)時(shí)被打回還要重新找,。萬(wàn)一遇到了模版更換Logo一類(lèi)的事情，用提心吊膽來(lái)形容有時(shí)候都不過(guò)分,。

  
  

• 把討論和筆記寫(xiě)入文檔：雖然有模版，但還是會(huì)常常見(jiàn)到字體五花八門(mén),、行間距大小不一,、色調(diào)五彩繽紛……對(duì)待這些問(wèn)題，讀者只能呵呵了（本文如果哪天寫(xiě)入了某個(gè)Word模版,，肯定也是個(gè)鬼樣）,。

  
  

• 合寫(xiě)文檔的痛苦：通常的模式是：牽頭人把章節(jié)定一下，在章節(jié)后面把具體撰寫(xiě)人的名字寫(xiě)上,，約定個(gè)時(shí)間,，牽頭人手工合并。問(wèn)題顯而易見(jiàn)啦：

  • 手工合并易出錯(cuò)

  • 具體撰寫(xiě)人需要修改時(shí)會(huì)去麻煩牽頭人,，要么牽頭人不斷合并,，要么撰寫(xiě)人采取保守策略不再積極提交變更

  • 合并文檔的版本管理困難：經(jīng)常會(huì)看到把日期加到文檔后，一連串的日期把自己累的不行

  • “指定章節(jié)到撰寫(xiě)人”打擊了撰寫(xiě)人寫(xiě)其他章節(jié)的積極性：因?yàn)闀?huì)給合并人帶來(lái)更多的工作和混淆,，撰寫(xiě)人寧可保持低調(diào),；同時(shí)撰寫(xiě)人并不知道另一章節(jié)的人是否已經(jīng)撰寫(xiě)了自己想到的內(nèi)容。

    
    

• 提交評(píng)審：挺好,。但其中有一點(diǎn)需要改進(jìn)：作者根據(jù)評(píng)審意見(jiàn)修改后,，通常有兩種方式評(píng)判是否OK：主持人直接評(píng)判，主持人開(kāi)會(huì)召集評(píng)委們?cè)俅卧u(píng)判,?！?在一個(gè)溫和的團(tuán)隊(duì)中，這兩種方式都會(huì)“和諧”的完成,?？梢栽黾拥?種意見(jiàn)表達(dá)的方式：評(píng)委直接修改文檔，然而在word模版+沒(méi)有版本管理的方式下,，這是令人望而卻步的,。

  
  

• 更新文檔：最痛苦的部分到了

  • 需求、方案類(lèi)文檔：開(kāi)發(fā)實(shí)現(xiàn)后回頭更新需求,、方案的比例有多高,？這個(gè)現(xiàn)實(shí)問(wèn)題很多同學(xué)寧可提都不提， Let it go,，隨她吧,。

  • 詳設(shè)、開(kāi)發(fā)類(lèi)文檔：軟硬件工程師們拿各種理由來(lái)搪塞的場(chǎng)景相信都遇到過(guò)吧,，什么“來(lái)不及”了,、“太多了”,、“更新太快了”……甚至還有“代碼即文檔”這種左傾冒險(xiǎn)主義的托辭不一而足。面對(duì)領(lǐng)導(dǎo)燃燒的怒火,，工程師們用微笑和聳肩來(lái)抵擋,。

  • 測(cè)試、報(bào)告類(lèi)文檔：這個(gè)還好,，因?yàn)槭且淮涡曰顒?dòng)的文檔產(chǎn)物,，基本不需要更新?！稖y(cè)試方案》歸屬到第一類(lèi)中,。

  • 其他：技術(shù)積累、會(huì)議紀(jì)要等過(guò)程文檔,，細(xì)想想更恐怖,，幾個(gè)月前討論的會(huì)議紀(jì)要你還會(huì)打開(kāi)么？到哪里找估計(jì)都忘了吧,，那次會(huì)議中的決議還記得么,？上次調(diào)試遇到的挫折寫(xiě)入技術(shù)積累了么？…… 呀呀呀,，不要再說(shuō)了,。呵呵。

    
    

• 更新后文檔的推送：有幾種方式

  • 第一次你是通過(guò)郵件,、聊天軟件把文檔發(fā)給讀者的,，更新后的文檔則需要重發(fā)一次，如果你一個(gè)月更新一次還好,，如果一周更新一次呢,？一天呢？

  • 文檔在某某系統(tǒng)中歸檔的：這就要依賴(lài)與該系統(tǒng)是否好用,、方便了,。如果想讀一個(gè)文檔要進(jìn)入系統(tǒng)中能夠快速找到，Good,；如果需要多次跳轉(zhuǎn),、或者要掌握什么奇技淫巧才行，就又要呵呵了,，就是這次進(jìn)去找到了,，下次可能又找不到了?！?在某某系統(tǒng)中迷過(guò)路的小伙伴請(qǐng)舉下手,。

    
    

上面這些如果有哪條戳中了你的痛點(diǎn)，請(qǐng)繼續(xù)往下讀,。如果你覺(jué)得沒(méi)關(guān)系啦,，這些都是小事,，雞毛蒜皮的，我們團(tuán)隊(duì)可以克服,，那就請(qǐng)不用往下看了,，謝謝！

文檔的新方式

現(xiàn)在,，我們來(lái)試想下一種新的方式：

1. 寫(xiě)作和排版是分離的：作者只關(guān)心內(nèi)容和簡(jiǎn)單的排版（如標(biāo)題,、分段、列表）,，不關(guān)心最終的排版布局、字體色調(diào)等表現(xiàn)形式（如顏色,、字體,、行間距……），類(lèi)似書(shū)籍出版業(yè)：作者只需要把內(nèi)容寫(xiě)在稿紙上或txt文本,，編輯去完成排版和書(shū)籍的美工,。這樣帶來(lái)的優(yōu)點(diǎn)很多：

   • 作者專(zhuān)注于寫(xiě)內(nèi)容、表達(dá)思想

   • 編輯可以使得表現(xiàn)形式很容易統(tǒng)一

     • 一個(gè)公司,、一個(gè)部門(mén),、或一個(gè)團(tuán)隊(duì)可以方便的制定自己的渲染方式,，寫(xiě)作的人可以不必關(guān)心。

     • 更換Logo這種事情只需要編輯一個(gè)人做就是了,。

   • 編輯不是人，是軟件,、電腦

     
     

2. 多人合寫(xiě),、協(xié)作是非常方便的：每個(gè)人的觀點(diǎn)和想法可以方便的在團(tuán)隊(duì)中流動(dòng)，關(guān)鍵是可以被記錄在文檔中,，而不是散落在郵件里,。

   • 每個(gè)人可以即時(shí)、及時(shí)的對(duì)文檔中的內(nèi)容表達(dá)意見(jiàn),。

   • 團(tuán)隊(duì)中每個(gè)人都可以即時(shí)的收到文檔被更新的通知,，而且不需要撰寫(xiě)人發(fā)郵件通知，尤其在撰寫(xiě)人是多人的時(shí)候更加有效,。

     
     

3. 寫(xiě)作是簡(jiǎn)文本形式的：隨時(shí),、隨處、隨編輯器可打開(kāi),、編輯,，再也不會(huì)出現(xiàn)在一個(gè)沒(méi)有安裝Office的電腦上打不開(kāi)一個(gè)word文檔、打開(kāi)文檔后一個(gè)visio圖是個(gè)紅色叉叉……的囧境,。

   
   

4. 文檔更新歷史信手拈來(lái),，毫厘不差：不必人工更新文檔中的某個(gè)叫做“更新歷史”的章節(jié),，而是能夠方便的看到該文檔的所有參與人、參與時(shí)間,、和修訂內(nèi)容,。——這可不是word的修訂模式能夠完成的,。

   
   

5. 通過(guò)瀏覽器訪問(wèn)文檔：打開(kāi)IE/Chrom/FF,，訪問(wèn)網(wǎng)址既能看到最新的文檔，收藏到收藏夾中時(shí)不時(shí)看看,，甚至可以進(jìn)行RSS訂閱 —— 這種閱讀體現(xiàn)還不能打動(dòng)你么,？

   
   

OK，幾大夢(mèng)想如何來(lái)實(shí)現(xiàn)呢,？非常方便,，我們現(xiàn)在所處的互聯(lián)網(wǎng)時(shí)代早就搞定這些事情了，并且是非常簡(jiǎn)單,、高效,，需要的只是你勇敢的去嘗試、然后喜歡,。

• 使用Markdown等標(biāo)記類(lèi)語(yǔ)言來(lái)寫(xiě)簡(jiǎn)文本文檔：編輯器很多,，可以參考下文“工具軟件”章節(jié)，此處我推薦SublimeText,，Win/Mac/Linux全系統(tǒng)通用,，適當(dāng)?shù)募由细鞣N插件，寫(xiě)什么都特有感,。

  
  

• 使用SCM(svn,、git等)管理簡(jiǎn)文本文檔：并不是什么都能用SCM管理，至少軟件版本,、壓縮包,、視頻、甚至圖片……這些二進(jìn)制的東西都是不能交給SVN,、git來(lái)管理的,，倒不是scm不能管理，而是你在做不對(duì)的事情,，就像非要一個(gè)軟件工程師去畫(huà)一塊電路板,，不是他做不出來(lái)，而是你用人不當(dāng),。簡(jiǎn)文本是svn/git最能接受的,，并且好處多多：

  • 多人合寫(xiě)文檔：在svn/git提交就是了，update一下，然后commit,，什么牽頭人,、合并人都不再需要了

  • 修改別人的章節(jié)：update后，修改就是了,，提交后能方便地看到修改了啥,，還能回退

  • 促進(jìn)文檔更新：能看到log和每次更改的記錄，就像一個(gè)成績(jī)肯定,，會(huì)建立作者的成就感,，越是不斷更新文檔的人，看著自己的更新log,，越是更充滿再更新一下,、再完美一點(diǎn)的沖動(dòng)。

  • 對(duì)開(kāi)發(fā)工程師沒(méi)抵觸：當(dāng)前的開(kāi)發(fā)工程師99%都已經(jīng)熟練的掌握了svn或git的使用,，剩下1%可能還在使用cvs或clearcase,。所以問(wèn)題是如何讓系統(tǒng)工程師、測(cè)試工程師等其他人員也掌握svn或git這種可以1h入門(mén)速成的好工具（git的精通還是需要更多的時(shí)間和實(shí)踐,，svn則基本沒(méi)有精通的必要了）。

    
    

• 配置HttpServer完成編輯角色：Markdown撰寫(xiě)的文檔當(dāng)然也可以在本地靜態(tài)編譯成html,，自己查看,，或分發(fā)給朋友，但這樣做的缺點(diǎn)是把編輯工作自己承擔(dān)了,，后果就是模版不統(tǒng)一,，這種團(tuán)隊(duì)中不可取。由HttpServer中加Markdown渲染插件：把編輯工作交給服務(wù)器是更好的選擇,。

  
  

• 加入權(quán)限控制：svn,、httpserer都可以進(jìn)行權(quán)限控制，控制某些人不能提交或閱讀,。

  
  

總結(jié)一下：回頭一看,，你會(huì)發(fā)現(xiàn)，這不就是寫(xiě)代碼么,？做軟件的都懂這個(gè),。—— 就是,，就是,，就像寫(xiě)代碼一樣來(lái)寫(xiě)文檔，對(duì)軟件工程師簡(jiǎn)直是零門(mén)檻,，呵呵,。

文檔的代碼化

這里需要首先分辨出兩個(gè)概念：

1. 代碼的文檔化：是對(duì)工程師的期望，期望軟硬件工程師寫(xiě)出的代碼是盡量不需要外部文檔的，或能夠自動(dòng)生成文檔的,。

   • 加強(qiáng)有價(jià)值的注釋?zhuān)哼@個(gè)對(duì)大部分工程師都是不抵觸的

   • 書(shū)寫(xiě)更易讀的源碼：有意義的變量/函數(shù)命名,、更合理的函數(shù)原子分解、避免奇技淫巧的語(yǔ)法使用……

   • 盡量不需要外部文檔：

   • 自動(dòng)生成文檔：按照某種語(yǔ)法書(shū)寫(xiě)注釋?zhuān)幾g時(shí)使用Doxygen等工具自動(dòng)生成注釋,。對(duì)內(nèi)部接口可能作用不大,，但對(duì)模塊間接口和對(duì)外服務(wù)接口，自動(dòng)生成文檔非常重要和必要,，甚至可以說(shuō),，不是自動(dòng)生成的文檔都是不能用的文檔。

     
     

2. 文檔的代碼化：是對(duì)所有寫(xiě)文檔人的期望,，期望所有寫(xiě)文檔的人能夠掌握svn/git等工具,，采用簡(jiǎn)文本格式書(shū)寫(xiě)文檔，適當(dāng)加入標(biāo)記類(lèi)語(yǔ)言,，克服傳統(tǒng)文檔書(shū)寫(xiě),、合并、發(fā)布,、更新過(guò)程中的痛點(diǎn),，寫(xiě)出喜聞樂(lè)見(jiàn)、快速迭代,、有效傳播的文檔,。

   
   

代碼文檔化是另外一個(gè)課題，本文不表,。

文檔代碼化是本人提出的新名詞,，百度上暫時(shí)還搜不到，提出這樣的名詞主要還是為了促進(jìn)更多的人改進(jìn)原有的文檔編寫(xiě)方式,。

那么文檔代碼化除了個(gè)人視野眼界和接受新事物的能力兩點(diǎn)阻力之外,，還有沒(méi)有其他的困難呢？當(dāng)然有：

• 并不是所有文檔都適合代碼化：正式嚴(yán)肅,、需要加密,、紅頭文件之類(lèi)的應(yīng)該更適合使用傳統(tǒng)方式

• markdown標(biāo)準(zhǔn)在不斷演化中，并且已經(jīng)開(kāi)始有分支能夠強(qiáng)力到影響創(chuàng)始人的決策

• markdown的編輯工具雖然好找,，但編譯工具并不是很統(tǒng)一

  • 對(duì)擴(kuò)展語(yǔ)法的編譯不一致,，尤其是對(duì)頁(yè)內(nèi)跳轉(zhuǎn)、TOC等標(biāo)準(zhǔn)的實(shí)現(xiàn)

  • 本地編譯和HttpServer訪問(wèn)時(shí)編譯的實(shí)現(xiàn)難度不一樣

    • 對(duì)個(gè)人：本地編譯,，直接傳給讀者h(yuǎn)tml文件即可

    • 對(duì)團(tuán)隊(duì)：建議是只向svn/git上傳markdown文件,，不編譯，而是在讀者訪問(wèn)httpserver時(shí)即時(shí)編譯,。

      
      

下面開(kāi)始解決上面的幾個(gè)小困難 —— 說(shuō)實(shí)話這些對(duì)軟件工程師不算困難,，有N多的開(kāi)源項(xiàng)目可以拿來(lái)主義，但對(duì)其他團(tuán)隊(duì)有可能是個(gè)不大不小的困難,，還是描述一下吧,。

實(shí)現(xiàn)篇

Markdown基礎(chǔ)

熟悉、已經(jīng)會(huì)使用markdown的同學(xué)請(qǐng)?zhí)^(guò)本章節(jié),。

標(biāo)記語(yǔ)言與Markdown

計(jì)算機(jī)的可讀文本記錄有兩種：簡(jiǎn)文本方式,、富文本方式

兩者各有優(yōu)缺點(diǎn),，長(zhǎng)期以來(lái)互補(bǔ)而不能互相替代。

但是到了網(wǎng)絡(luò)時(shí)代,，移動(dòng)閱讀日漸成風(fēng),，追求簡(jiǎn)潔閱讀,，隨之也帶動(dòng)桌面閱讀一起，都在向“扁平化,、去擬物,、沉浸式”發(fā)展，富文本的豐富似乎變得可有可無(wú)（其實(shí)本來(lái)word的豐富表現(xiàn)力又有幾人會(huì)用,？80%的人群只用了富文本編輯工具的20%功能,，其實(shí)是另外80%的功能變得可有可無(wú)）。

有沒(méi)有結(jié)合兩者優(yōu)點(diǎn)：簡(jiǎn)文本書(shū)寫(xiě),、（?。└晃谋颈憩F(xiàn)的產(chǎn)物呢,？—— 有：標(biāo)記語(yǔ)言（markup language）,，在文本中插入格式描述。

其實(shí)并不是近幾年才開(kāi)始有人關(guān)注兩種文本的融合,，標(biāo)記語(yǔ)言也已經(jīng)發(fā)展了很多年,，也不止一種：

• TeX

• XML

• Markdown

• DocBook

都是在文本中插入格式描述，孰優(yōu)孰劣暫且不表，這里只說(shuō)一個(gè)：隨著github的風(fēng)靡而在廣大程序直男中迅速普及的：markdown,。

markdown的細(xì)節(jié)本文不表,，可參考：

• 了解：

  • 百度百科

  • 維基百科

• 創(chuàng)始人：John Gruber

  • 維基百科

  • 個(gè)人網(wǎng)站：DARING FIREBALL http:///

• 語(yǔ)法：

  • John Gruber 基礎(chǔ)語(yǔ)法 http:///projects/markdown/

  • GFM（GitHub Flavored Markdown） https://help.github.com/articles/github-flavored-markdown/ —— github 擴(kuò)展，已廣泛流行

    
    

Markdwon工具軟件

我本人對(duì)比試用過(guò)的幾款如下表,。列出來(lái)只是想給大家多一些選擇,，如果有選擇恐懼癥的同學(xué)，跳過(guò)本節(jié),，參考附錄1,，使用 sublime + MarkdownEditor + MarkdownPreview 即可。

點(diǎn)評(píng)

• Haroopad：偶然發(fā)現(xiàn)的通吃,、美觀,、功能強(qiáng)悍的全能型選手

• Mou：好久沒(méi)升級(jí)了，又聽(tīng)說(shuō)作者正在考慮出售,，看來(lái)已經(jīng)日落西山了,。

• MarkdownPad：基于.NET Framework4.0，啟動(dòng)稍顯慢,，其他都挺好,。

• Sublime Text + Plugin：強(qiáng)烈推薦，取代了我Windows上的Notepad++,，F(xiàn)edora上的gedit,，和Mac上的TextEdit，以1抵3,。其實(shí)VI也能做到以1抵3的,，VI也有Markdown插件，但Sublime有VI模式,，但VI沒(méi)有Sublime的很多特性,，只能說(shuō)：VI加油！

  
  

工作流

工作流1：本地靜態(tài)生成HTML

1. 書(shū)寫(xiě)markdown文檔

2. 本地編譯為HTML

3. markdown文檔和HTML同時(shí)上傳到svn/git服務(wù)器

4. 讀者通過(guò)權(quán)限受控的http訪問(wèn)svn服務(wù)器上的html文件

   
   

工作流2：HttpServer動(dòng)態(tài)生成HTML

1. HttpServer管理員配置好服務(wù)器

2. 書(shū)寫(xiě)markdown文檔

3. 僅上傳markdown文件到svn/git服務(wù)器

4. 讀者受權(quán)限控制的通過(guò)http訪問(wèn)svn服務(wù)器上的markdown文件,，動(dòng)態(tài)轉(zhuǎn)換為html

對(duì)比兩種工作流,，由于每個(gè)人轉(zhuǎn)換markdown的方式可能有所不同，甚至markdown轉(zhuǎn)換html可能對(duì)某些同學(xué)是個(gè)麻煩,。我建議采用工作流2,，只需管理員做一次配置，后續(xù)的轉(zhuǎn)換都不成問(wèn)題,，只需要規(guī)范大家的書(shū)寫(xiě),。

最后，上幾幅高清無(wú)碼大圖來(lái)賞析一下,。

sublime中暢快的書(shū)寫(xiě)和預(yù)覽markdown

通過(guò)SVN來(lái)合并,、更新文檔,，并查看修改記錄，快捷追溯

配置Apache識(shí)別.md文件

通過(guò)瀏覽器訪問(wèn).md后綴的Markdown文件(截圖中為本文的網(wǎng)絡(luò)地址)

一些技術(shù)細(xì)節(jié)

• 動(dòng)態(tài)生成HTML的HttpServer配置

  • HttpServer的Markdown轉(zhuǎn)換插件還是不難找的,，無(wú)論是IIS還是Apache,，比如Apache上有：

    • https://github.com/sminnee/markdown-handler.git

    • https://github.com/erusev/parsedown

  • 現(xiàn)在可以這樣訪問(wèn)md文件了：http://./ReadMe.md 比如本文：http://./articles/experiences/用寫(xiě)代碼的方式寫(xiě)文檔/用寫(xiě)代碼的方式寫(xiě)文檔.md —— 如果你閱讀的是word版，不妨閱讀一下網(wǎng)頁(yè)版,，與word相比,，會(huì)經(jīng)常更新的哦。

    
    

• TOC：為文檔生成一份目錄,，并且能夠頁(yè)內(nèi)跳轉(zhuǎn)，富文本文檔都是能輕松實(shí)現(xiàn)的,，也是非常有必要的。Markdown最初沒(méi)有,，后來(lái)加上了,。

  • TOC語(yǔ)法標(biāo)準(zhǔn)：https:///Markdown/extensions/toc.html

  • TOC的生成：可以使用submlime的 MarkdownTOC 插件

  • HeaderAnchor的生成：

    • 使用MarkdownPreview生成的本地HTML具有標(biāo)準(zhǔn)的HeaderAnchor

    • 使用parsedown生成的動(dòng)態(tài)HTML,，暫時(shí)沒(méi)有,。自己動(dòng)手修改了一下吧,，PHP寫(xiě)的,，然后還可以貢獻(xiàn)給原作者,。如果對(duì)PHP不太熟悉，百度一下學(xué)學(xué)也就半天時(shí)間,。如果沒(méi)學(xué)過(guò)軟件,，就直接到我的github（https://github.com/wkevin/parsedown）上取一下也行。

      
      

附錄

SublimeText的基本使用

一定要分清標(biāo)記類(lèi)語(yǔ)言的：編輯器和編譯器,。Sublime只是編輯器，MarkdownEditor和MarkdownTOC是編輯器輔助插件,，MarkdownPreview是編譯插件,。

安裝

• 安裝軟件：官網(wǎng)http://www./ 發(fā)布安裝包和綠色免安裝包,，區(qū)別是：用戶數(shù)據(jù)（包括：自己安裝的插件,、緩存、配置等）

  • 安裝版在：C:\Users\Administrator\AppData\Roaming\Sublime Text 3\

  • 免安裝版：運(yùn)行目錄\Data\

  • 所以免安裝版打個(gè)包就能傳給另一臺(tái)電腦使用了,，所有用戶數(shù)據(jù)都在,，非常方便

• 安裝插件：

  1. 首先安裝Package Control https://sublime./，

  2. 然后Ctrl+Shift+P

  3. 輸入install package

  4. 分別輸入插件的名字：MarkdownEditor 和 MarkdownPreview

     
     

     
     

基本操作

• Goto

  • （搜索后）跳轉(zhuǎn)
    

    • 跳轉(zhuǎn)到文件：Ctrl+P：

    • 跳轉(zhuǎn)到symbol：Ctrl+P,，@,，或Ctrl+R

    • 跳轉(zhuǎn)到word：Ctrl+P，#,，或Ctrl+;

    • 跳轉(zhuǎn)到line：Ctrl+P,，:，或Ctrl+g

    • 跳轉(zhuǎn)到定義：F12——ST3中新增,，需要文件首先加入到project中

  • 向回和向前跳轉(zhuǎn)：Alt+-和Alt+Shift+-

  • 文件切換

    • Tab直接定位：Alt+1/2/3/...

    • Tab間切換：Ctrl+PageDown/Up

    • 頭文件和源文件之間切換：Alt+O

      
      

• Select

  • Multiple Selections（多重選擇）
    

    • Ctrl+鼠標(biāo)左鍵：同時(shí)在多個(gè)地方放置光標(biāo)，然后可進(jìn)行同時(shí)的修改,、刪除等

    • Ctrl+D：選中相同的word

      
      

    • 依次Ctrl+D,，選中每一個(gè)想要的，然后可進(jìn)行同時(shí)的修改,、刪除等
      

    • 遇到某個(gè)不想要的,，用Ctrl+K&Ctrl+D跳過(guò)

    • 取消選定：Ctrl+U

    • 上述兩種操作也可以組合使用：先 Ctrl+D，在Ctrl+左鍵選……

  • Column Selection

    • Windows：Ctrl+Alt+Up/Down,，或者Shift+右鍵拖動(dòng)

    • Linux：Alt+?+Up/Down

    • OS X：?+?+Up/Dow

      
      

• Tools

  • Command Pallete（命令操作）：Ctrl+Shift+P

配置

• Preferences --> Settings

  • 切換到 vi 模式
    

    • Setting-Default：拷貝 'ignored_packages': ['Vintage']——Default是修改不了的

    • Setting-User：粘貼為 'ignored_packages': [ ]——User的設(shè)置會(huì)覆蓋Default

    • 基本的字符,、搜索,、行、列……操作都是使用vi的快捷鍵實(shí)現(xiàn),，就不去再記憶一份ST的快捷鍵了

      
      

• command,、Keybinding,、macro ——三者是關(guān)聯(lián)的。

  • command
    

    • wiki:http://sublime-text-unofficial-documentation./en/latest/reference/commands.html
      

    • 官方（不全）：https://www./docs/commands

  • key bindings
    

    • 書(shū)寫(xiě)格式：http://sublime-text-unofficial-documentation./en/latest/reference/key_bindings.html?highlight=keys
      

  • macro

    • 書(shū)寫(xiě)格式：http://sublime-text-unofficial-documentation./en/latest/extensibility/macros.html?highlight=macro

    • macro的一個(gè)缺點(diǎn)：宏只能識(shí)別Text Commands,，不能識(shí)別很多command,，比如show_overlay

Plugin

• Package Control: https://sublime./ 下面各種插件的基礎(chǔ)、管家

  
  

• Markdown類(lèi)

  • Markdown Preview：https://sublime./packages/Markdown%20Preview

    • Preview：兩種方式

      （1）cmd+shift+P：

      • Markdown Preview: Preview in Browser

      • Markdown Preview: Export HTML in Sublime Text

      • Markdown Preview: Copy to Clipboard

      • Markdown Preview: Open Markdown Cheat sheet

      （2）Ctrl+B(Windows/Linux) or cmd+B(Mac)： build current file到當(dāng)前目錄,，并且名字相同,，后綴改為.html

    • Config

      • 'css': 'E:/kevin/kknowledge/src/CSS/markdown.css',

      • 'image_path_conversion': 'none',——不要把圖片的相對(duì)地址轉(zhuǎn)換為絕對(duì)地址，否則本地路徑就進(jìn)去了,，非常不好

      • 'file_path_conversions': 'none',——同上

      • 'path_tempfile': './',——cmd+shift+P生成的臨時(shí)html文件地址,，該臨時(shí)文件名為隨機(jī)

      • 'enable_autoreload': false,——save的時(shí)候是否build,，true的話save會(huì)很慢

  • Markdown Edit
    

    （1）Provides a decent Markdown color scheme

    （2）加快文件的操作

    • Pair 操作

      • 輸入一對(duì)的首,，自動(dòng)加入尾,；

      • 輸入首后前刪首,，自動(dòng)刪除尾；

      • 輸入首后空格,，自動(dòng)刪除尾；

    • 列表的支持

      • 列表的編輯中,，回車(chē)自動(dòng)加入列表項(xiàng)

      • Tab和Shift Tab列表級(jí)別增加一級(jí),、減少一級(jí)

    • ~ wraps selected text with ~~ (strikethrough)

  • MarkdownTOC：安裝后操作： 菜單Tools -- MarkdownTOC -- insert

    
    

    
    

• 字符編碼類(lèi)：SublimeText 新建,、保存默認(rèn)都是 UTF-8,，所以只存在這樣兩種動(dòng)作：其他編碼格式的文件打開(kāi)時(shí)沒(méi)有被正確識(shí)別——需要repon或reload,；無(wú)論當(dāng)前打開(kāi)的文件是什么編碼,，我想保存為一種我指定的格式——save with或set file encoding to,。

  • EncodingHelper：官方出品,，菜單中會(huì)增加reopen/save with encoding,，但缺少ANSI（GBK,、GB2312……）的支持。

  • ConverToUTF8：中國(guó)的同學(xué)補(bǔ)充,，菜單中會(huì)增加Set File encoding to/Reload with encoding，不過(guò)名字容易讓人困擾,，改為EncodingHelperWithANSI更合適些。