一、無(wú)規(guī)范不和諧
俗話說(shuō)"無(wú)規(guī)矩不成方圓"螟左，但是我要說(shuō)無(wú)規(guī)范不和諧憨愉，你可能覺得言重了「言重個(gè)毛」艰额，下面就簡(jiǎn)單的說(shuō)一下吧
- 公司沒有規(guī)范可以嗎「那不亂了套了」
- 人事招人沒有規(guī)范可以嗎「隨便拿個(gè)人來(lái)就用匆骗，你估計(jì)會(huì)被人說(shuō)秀逗了」
- 團(tuán)隊(duì)管理沒有規(guī)范可以嗎「誰(shuí)特么鳥你」
- 開發(fā)人員沒有文檔（各種文檔）可以嗎「NM,連個(gè)需求文檔都沒有劳景，做個(gè)毛毛，這句話不陌生吧」
- 你沒有規(guī)范能找到自己喜歡的女（男）朋友绰筛？「還不是按自己的規(guī)范和標(biāo)準(zhǔn)來(lái)衡量的」
- 特別是開發(fā)語(yǔ)言枢泰，如果沒有規(guī)范描融，你全部亂整铝噩，還有其它等等各種規(guī)范
來(lái)一個(gè)場(chǎng)景對(duì)話吧，以開發(fā)一個(gè) APP 為例子來(lái)說(shuō)明「純屬虛構(gòu)窿克，如有雷同那真是中獎(jiǎng)了」骏庸，小明「開發(fā) client」，小張「開發(fā) server」
如此類似的事情的在需求年叮、產(chǎn)品具被、銷售、運(yùn)營(yíng)等等各個(gè)地方都會(huì)出現(xiàn)只损，何也--沒有規(guī)范一姿，最后導(dǎo)致權(quán)責(zé)不明七咧，各干各的，反工是家常便飯叮叹，更甚者會(huì)干起架來(lái) ...
無(wú)規(guī)范不和諧艾栋，花很小的代價(jià)獲取更多大價(jià)值有時(shí)就體現(xiàn)在規(guī)范當(dāng)中，規(guī)范最好以書面的形式「別拿嘴說(shuō)蛉顽，誰(shuí)也不會(huì)記的」蝗砾，規(guī)范的編寫有多種形式，今天我們就來(lái)看看其中一個(gè) docsify「文檔網(wǎng)站生成工具」
二携冤、docsify
寫文檔歷程
規(guī)范基本上都以文檔的形式出現(xiàn)的悼粮，寫文檔我們可以使用的工具實(shí)在太多了，小到記事本曾棕，大到一個(gè)綜合軟件太多太多了扣猫，先說(shuō)一下筆者主要使用的文檔編寫工具，分為兩個(gè)階段「未了解 markdown 之前和之后」
- 1翘地、最開始使用 excel苞笨、word 「未了解 markdown 之前」
- 2、后面使用 oschina 的 git readme 「基于 markdown 語(yǔ)法」
- 3子眶、使用 gitbook 來(lái)編寫文檔或記筆記 「基于 markdown 語(yǔ)法」
- 4瀑凝、使用 hexo 來(lái)編寫文章或文檔 「基于 markdown 語(yǔ)法」
現(xiàn)在我大部分使用 gitbook 來(lái)記筆記和寫文檔，只要把 markdown 語(yǔ)法熟悉了玩起這些來(lái)都是小菜臭杰，簡(jiǎn)書粤咪、csdn、掘金等自媒體平臺(tái)都支持 markdown 了渴杆，markdown 一定要掌握「現(xiàn)在還不懂 markdown 那就太 low 了」寥枝，簡(jiǎn)單的說(shuō)一下 gitbook 的流程
- 1、使用 markdown 來(lái)編寫對(duì)應(yīng)的文檔或電子書界面
- 2磁奖、使用 gitbook build 會(huì)把 markdown 文件轉(zhuǎn)化成 .html 文件
- 3囊拜、直接發(fā)布 html 文件即可「在網(wǎng)站上就可以瀏覽了」，當(dāng)然你也可以把電子書轉(zhuǎn)化成 pdf 來(lái)查看
gitbook 有多種玩法比搭，有興趣的可以看看這部分內(nèi)容
docsify 簡(jiǎn)介
用官方的話來(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 的開發(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è)毛毛呢穴亏，直接并行開發(fā)吧「還 qq 對(duì)接蜂挪？重挑，還拿嘴對(duì)接？」
docsify 目錄解析
由于 docsify 的文檔非常的詳細(xì)棠涮，我們照著一點(diǎn)點(diǎn)的配置和編寫半個(gè)小時(shí)就能入門攒驰，這里我們就把以上完成的 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è)诖酥袑懙卿浗涌?/p>
對(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 編輯等等插件」，也可以自己開發(fā)插件等「非常豐富官脓，我們可以看官網(wǎng)查看」
五协怒、部署
我們寫的文檔可以部署在 GitHub Pages 上，也可以部署在所有的靜態(tài)文件服務(wù)器上等
六卑笨、總結(jié)
這節(jié)我們簡(jiǎn)單介紹了一下 docsify 文檔編寫工具孕暇，只是起了一個(gè)拋磚引玉的作用，具體的好多玩法大家可以自行去探所赤兴，當(dāng)然拿 docsify 來(lái)寫筆記是非常不錯(cuò)的「筆者一直使用 gitbook 來(lái)寫筆記」妖滔，還可以用它來(lái)寫個(gè)博客啥的都是不錯(cuò)的
如果還不熟悉 markdown 語(yǔ)法的，建議現(xiàn)在就看一定要把它掌握了「簡(jiǎn)單又牛 B 桶良，寫個(gè)模版什么的使用 markdown 再適合不過(guò)了」
案例地址：https://github.com/tigerchain/docsifydemo
作者: TigerChain 訂閱查看更多內(nèi)容座舍。
本文出自 TigerChain 侃大山
公號(hào): TigerChain
