一、無(wú)規(guī)范不和諧
俗話(huà)說(shuō)"無(wú)規(guī)矩不成方圓"，但是我要說(shuō)無(wú)規(guī)范不和諧，你可能覺(jué)得言重了「言重個(gè)毛」，下面就簡(jiǎn)單的說(shuō)一下吧
- 公司沒(méi)有規(guī)范可以嗎「那不亂了套了」
- 人事招人沒(méi)有規(guī)范可以嗎「隨便拿個(gè)人來(lái)就用，你估計(jì)會(huì)被人說(shuō)秀逗了」
- 團(tuán)隊(duì)管理沒(méi)有規(guī)范可以嗎「誰(shuí)特么鳥(niǎo)你」
- 開(kāi)發(fā)人員沒(méi)有文檔（各種文檔）可以嗎「NM,連個(gè)需求文檔都沒(méi)有，做個(gè)毛毛，這句話(huà)不陌生吧」
- 你沒(méi)有規(guī)范能找到自己喜歡的女（男）朋友？「還不是按自己的規(guī)范和標(biāo)準(zhǔn)來(lái)衡量的」
- 特別是開(kāi)發(fā)語(yǔ)言，如果沒(méi)有規(guī)范，你全部亂整，還有其它等等各種規(guī)范
來(lái)一個(gè)場(chǎng)景對(duì)話(huà)吧，以開(kāi)發(fā)一個(gè) APP 為例子來(lái)說(shuō)明「純屬虛構(gòu)，如有雷同那真是中獎(jiǎng)了」，小明「開(kāi)發(fā) client」，小張「開(kāi)發(fā) server」
如此類(lèi)似的事情的在需求、產(chǎn)品、銷(xiāo)售、運(yùn)營(yíng)等等各個(gè)地方都會(huì)出現(xiàn)，何也--沒(méi)有規(guī)范，最后導(dǎo)致權(quán)責(zé)不明，各干各的，反工是家常便飯，更甚者會(huì)干起架來(lái) ...
無(wú)規(guī)范不和諧，花很小的代價(jià)獲取更多大價(jià)值有時(shí)就體現(xiàn)在規(guī)范當(dāng)中，規(guī)范最好以書(shū)面的形式「別拿嘴說(shuō)，誰(shuí)也不會(huì)記的」，規(guī)范的編寫(xiě)有多種形式，今天我們就來(lái)看看其中一個(gè) docsify「文檔網(wǎng)站生成工具」
二、docsify
寫(xiě)文檔歷程
規(guī)范基本上都以文檔的形式出現(xiàn)的，寫(xiě)文檔我們可以使用的工具實(shí)在太多了，小到記事本，大到一個(gè)綜合軟件太多太多了，先說(shuō)一下筆者主要使用的文檔編寫(xiě)工具，分為兩個(gè)階段「未了解 markdown 之前和之后」
- 1、最開(kāi)始使用 excel、word 「未了解 markdown 之前」
- 2、后面使用 oschina 的 git readme 「基于 markdown 語(yǔ)法」
- 3、使用 gitbook 來(lái)編寫(xiě)文檔或記筆記 「基于 markdown 語(yǔ)法」
- 4、使用 hexo 來(lái)編寫(xiě)文章或文檔 「基于 markdown 語(yǔ)法」
現(xiàn)在我大部分使用 gitbook 來(lái)記筆記和寫(xiě)文檔，只要把 markdown 語(yǔ)法熟悉了玩起這些來(lái)都是小菜，簡(jiǎn)書(shū)、csdn、掘金等自媒體平臺(tái)都支持 markdown 了，markdown 一定要掌握「現(xiàn)在還不懂 markdown 那就太 low 了」，簡(jiǎn)單的說(shuō)一下 gitbook 的流程
- 1、使用 markdown 來(lái)編寫(xiě)對(duì)應(yīng)的文檔或電子書(shū)界面
- 2、使用 gitbook build 會(huì)把 markdown 文件轉(zhuǎn)化成 .html 文件
- 3、直接發(fā)布 html 文件即可「在網(wǎng)站上就可以瀏覽了」，當(dāng)然你也可以把電子書(shū)轉(zhuǎn)化成 pdf 來(lái)查看
gitbook 有多種玩法，有興趣的可以看看這部分內(nèi)容
docsify 簡(jiǎn)介
用官方的話(huà)來(lái)說(shuō) docsify 一個(gè)神奇的文檔網(wǎng)站生成工具，如果看過(guò) vue 的官方文檔界面那就相當(dāng)于看到了 docsify 生成的界面了「很清爽有么有」
docsify 不同于 githbook 和 hexo 它不會(huì)生成將 .md 文件化成 .html 文件，這些轉(zhuǎn)化工作都是在運(yùn)行時(shí)進(jìn)行的
docsify 特性
部分使用 docsify 文檔
比如阿里 weex ui 的開(kāi)發(fā)文檔
這里就不一一列舉了，可以查看 https://github.com/docsifyjs/awesome-docsify/blob/master/README.md 的 showcase 部分
三、安裝并使用 docsify
安裝 docsify
npm i docsify-cli -g
這樣就安裝完了 docsify 命令行工具「前提要安裝 node」，安裝完以后我們就可以使用 docsify init ./docs 初始化項(xiàng)目了，然后運(yùn)行 docsify serve docs 就可以在本地跑一個(gè) server 來(lái)看到對(duì)應(yīng)生成的網(wǎng)站了
來(lái)個(gè)實(shí)例
無(wú)圖無(wú)直相
我們就來(lái)一個(gè) API 接口文檔吧，大概完成以后這樣的
還做一個(gè)國(guó)際化「只做了英文版的--裝個(gè) B 」,直接點(diǎn)擊上面導(dǎo)航的 EN 來(lái) Look 一下
怎么樣夠 B 格吧 ,服務(wù)端把這個(gè)文檔給出一扔，還管個(gè)毛毛呢，直接并行開(kāi)發(fā)吧「還 qq 對(duì)接？，還拿嘴對(duì)接？」
docsify 目錄解析
由于 docsify 的文檔非常的詳細(xì)，我們照著一點(diǎn)點(diǎn)的配置和編寫(xiě)半個(gè)小時(shí)就能入門(mén)，這里我們就把以上完成的 API 文檔目錄解析一下
主頁(yè) index.html
側(cè)邊欄 _sidebar.md
側(cè)邊欄對(duì)應(yīng)的網(wǎng)頁(yè)左邊的導(dǎo)航頁(yè)
_coverpage.md 封面
user/READMD.md
user/README.md 對(duì)應(yīng)的就是 user 的主頁(yè)，在這個(gè)例子中我們?cè)诖酥袑?xiě)登錄接口
對(duì)應(yīng)的就是我們?cè)谏蠄D中看到登錄接口「我們?cè)賮?lái)看一下，如下圖」
其它的 .md
其它的 getuserlist.md/getuserifno.md 都是側(cè)邊欄對(duì)應(yīng)的接口界面，這里就不一一說(shuō)了，和登錄界面是一樣的「不細(xì)說(shuō)了，文檔介紹的非常詳細(xì)」
我們大概介紹完了所制作的文檔，這里起一個(gè)拋磚引玉的作用，完了可以看 Demo 的源碼「上傳到 github 上，后面放出地址」
四、其它配置
可以定制主題、還有一插件列表「搜索、統(tǒng)計(jì)、在 github 編輯等等插件」，也可以自己開(kāi)發(fā)插件等「非常豐富，我們可以看官網(wǎng)查看」
五、部署
我們寫(xiě)的文檔可以部署在 GitHub Pages 上，也可以部署在所有的靜態(tài)文件服務(wù)器上等
六、總結(jié)
這節(jié)我們簡(jiǎn)單介紹了一下 docsify 文檔編寫(xiě)工具，只是起了一個(gè)拋磚引玉的作用，具體的好多玩法大家可以自行去探所，當(dāng)然拿 docsify 來(lái)寫(xiě)筆記是非常不錯(cuò)的「筆者一直使用 gitbook 來(lái)寫(xiě)筆記」，還可以用它來(lái)寫(xiě)個(gè)博客啥的都是不錯(cuò)的
如果還不熟悉 markdown 語(yǔ)法的，建議現(xiàn)在就看一定要把它掌握了「簡(jiǎn)單又牛 B ，寫(xiě)個(gè)模版什么的使用 markdown 再適合不過(guò)了」
案例地址：https://github.com/tigerchain/docsifydemo
作者: TigerChain 訂閱查看更多內(nèi)容。
本文出自 TigerChain 侃大山
公號(hào): TigerChain
