小小的改變，大大的化
基于docsify進(jìn)行文檔管理的內(nèi)部分享
一分苇、培訓(xùn)目的
通過(guò)近期與其他開發(fā)團(tuán)隊(duì)的溝通交流草则，發(fā)現(xiàn)他們對(duì)接口文檔的管理思路比較先進(jìn)、查閱方便等索抓；因此，有必要學(xué)習(xí)借鑒其他開發(fā)團(tuán)隊(duì)的接口文檔管理思路耸黑，通過(guò)研究發(fā)現(xiàn)他們使用的是docsify進(jìn)行接口文檔的管理，在業(yè)余時(shí)間對(duì)docsify進(jìn)行了一個(gè)簡(jiǎn)單的研究篮幢，抽出一定的時(shí)間為大家做一個(gè)簡(jiǎn)單的內(nèi)部分享大刊，本次分享的主要目的如下：
（1）提升開發(fā)團(tuán)隊(duì)接口文檔管理水平三椿；
（2）方便團(tuán)隊(duì)與其他項(xiàng)目組的溝通、交流搜锰；
（3）提高接口文檔的實(shí)用性伴郁、高效性；
（4）開發(fā)人員可以更加快速的查詢等纽乱；
在正式分享前鸦列，我們先看一下以下幾個(gè)接口查詢效果，具體如下圖所示：
二顽爹、培訓(xùn)內(nèi)容
2.1概況說(shuō)明
本次培訓(xùn)骆姐，主要包含如下內(nèi)容：
（1）docsify介紹及安裝；
（2）MD文件基本語(yǔ)法介紹肉渴；
（3）文檔管理demo演示带射；
（4）逐步掌握接口文檔的編寫；
2.2docsify介紹
2.2.1docsify介紹
docsify是一個(gè)文檔生成工具券勺，它直接加載 Markdown 文件并動(dòng)態(tài)渲染灿里，同時(shí)還可以生成封面頁(yè)。 不同于 GitBook匣吊、Hexo 的地方是它不會(huì)生成將 .md 轉(zhuǎn)成 .html 文件，所有轉(zhuǎn)換工作都是在運(yùn)行時(shí) 進(jìn)行侣灶。 docsify是由現(xiàn)餓了么前端團(tuán)隊(duì)@elemeFE的cinwell.li編寫的一套文檔站點(diǎn)生成框架缕碎，github上 已有3k+ star，這款框架和其他框架如gitbook等相比凡怎，最大的區(qū)別就在于docsify不是靜態(tài)生成html赊抖， 而通過(guò)動(dòng)態(tài)請(qǐng)求markdown編譯生成html。
2.2.2docsify特點(diǎn)
（1）無(wú)需構(gòu)建無(wú)需編譯房匆，寫完markdown文檔直接發(fā)布
（2）容易使用并且輕量 (~18kB gzipped)
（3）智能的全文搜索
（4）提供多套主題
（5）豐富的 API
（6）支持 Emoji
（7）兼容 IE10+
（8）支持 SSR (example)
（9）快速上手
2.2.3文檔規(guī)范的好處
（1）目錄、說(shuō)明清晰可見(jiàn)浴鸿；
（2）便于開發(fā)人員預(yù)覽查詢岳链；
（3）文檔更加方便維護(hù)；
2.2.4官方網(wǎng)址
對(duì)于具體的學(xué)習(xí)資料掸哑，大家可以參考官方網(wǎng)站。
2.2.5其它主流文檔管理
目前市面上有大致這么幾款主流的文檔生成站點(diǎn)厌蔽，分別為docsify摔癣、gitbook、Phenomic等拐云，可幫助用戶快速搭建文檔站點(diǎn)近她。其它三種在此不再贅述，喜歡的人員可以自行了解粘捎；需要說(shuō)明的是攒磨，目前微信相關(guān)的接口文檔使用的是gitbook進(jìn)行編寫的。
2.3安裝教程
2.3.1root安裝
推薦安裝 docsify-cli 工具娩缰，可以方便創(chuàng)建及本地預(yù)覽文檔網(wǎng)站。在安裝docsify-cli之前需要確保您首先安裝node浮毯。
npm i docsify-cli -g
2.3.2普通用戶下初始化項(xiàng)目
如果想在項(xiàng)目的 ./docs 目錄里寫文檔泰鸡，直接通過(guò) init 初始化項(xiàng)目。
docsify init ./docs
2.3.3開始寫文檔
初始化成功后饰迹，可以看到 ./docs 目錄下創(chuàng)建的幾個(gè)文件
-index.html 入口文件
-README.md 會(huì)做為主頁(yè)內(nèi)容渲染
-.nojekyll 用于阻止 GitHub Pages 會(huì)忽略掉下劃線開頭的文件
直接編輯 docs/README.md 就能更新網(wǎng)站內(nèi)容，當(dāng)然也可以寫多個(gè)頁(yè)面啊鸭。
2.3.4啟動(dòng)服務(wù)
運(yùn)行一個(gè)本地服務(wù)器通過(guò) docsify serve 命令可以方便的預(yù)覽效果莉掂，而且提供 LiveReload 功能千扔，可以實(shí)時(shí)的預(yù)覽。默認(rèn)訪問(wèn) http://localhost:3000 曲楚。
docsify serve docs
如果需要啟動(dòng)其他端口，可以直接在后面增加-p 4000表示啟動(dòng)端口為4000
更多命令行工具用法抚垃，參考 docsify-cli 文檔趟大。
2.3.5手動(dòng)初始化
如果不喜歡 npm 或者覺(jué)得安裝工具太麻煩逊朽，我們其實(shí)只需要直接創(chuàng)建一個(gè) index.html 文件。
index.html文件內(nèi)容具體如下：
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta charset="UTF-8">
<link rel="stylesheet" >
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
//...
}
</script>
<script src="http://unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>
2.3.6側(cè)邊欄
為了有側(cè)邊欄追他，那么你可以創(chuàng)建你自己的_sidebar.md：
首先岛蚤，你需要設(shè)置loadSidebar為true，詳細(xì)信息可在配置段落中找到单雾。
2.3.6.1 index.html配置如下所示：
<script> window.$docsify = { loadSidebar: true } </script> <script src="http://unpkg.com/docsify/lib/docsify.min.js"></script>
2.3.6.2側(cè)邊欄md配置
創(chuàng)建_sidebar.md：
<!-- docs/_sidebar.md -->
- [Home](/) - [Guide](guide.md)
2.3.7完整demo示例
index.html詳細(xì)配置示例如下所示：
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Document</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<!-- Theme: Simple -->
<!--
<link rel="stylesheet" >
-->
<link rel="stylesheet" href="assets/theme-simple.css">
<!-- Custom theme stylesheet -->
<link rel="stylesheet" href="assets/theme-custom.css">
<style>
nav.app-nav li ul {
min-width: 100px;
}
</style>
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
//定義路由別名铁坎，可以更自由的定義路由規(guī)則犁苏。 支持正則。
alias: {
'/.*/_sidebar.md': '/_sidebar.md'
},
// 加載 _sidebar.md,加載自定義側(cè)邊欄
loadSidebar: true,
//加載自定義導(dǎo)航欄
loadNavbar: false,
// 強(qiáng)制懸停,切換頁(yè)面后是否自動(dòng)跳轉(zhuǎn)到頁(yè)面頂部朴乖。
auto2top: true,
// 調(diào)整副標(biāo)題的級(jí)數(shù)
subMaxLevel: 2,
// 替換主題色
themeColor: '#4CAF50',
themeable: {
readyTransition : true, // default
responsiveTables: true // default
},
showLevel: true,
//文檔標(biāo)題，會(huì)顯示在側(cè)邊欄頂部买羞。
name: '',
//配置倉(cāng)庫(kù)地址或者 username/repo 的字符串畜普，會(huì)在頁(yè)面右上角渲染一個(gè) GitHub Corner 掛件。
repo: '',
//禁用 emoji 解析
noEmoji: true,
tocLevel: 6,
//搜索配置項(xiàng)
search: {
maxAge: 86400000, // 過(guò)期時(shí)間钝荡，單位毫秒舶衬，默認(rèn)一天
paths: 'auto', // or 'auto'
placeholder: '搜索',
noData: '找不到結(jié)果',
// 搜索標(biāo)題的最大程級(jí), 1 - 6
depth: 4
},
pagination: {
previousText: '上一章節(jié)',
nextText: '下一章節(jié)',
}
}
</script>
<script src="http://unpkg.com/docsify/lib/docsify.min.js"></script>
<script src="http://unpkg.com/docsify/lib/plugins/search.min.js"></script>
<script src="http://unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
<script src="http://unpkg.com/docsify-copy-code"></script>
<script src="http://unpkg.com/prismjs/components/prism-sql.min.js"></script>
<script src="http://unpkg.com/prismjs/components/prism-http.min.js"></script>
<script src="http://unpkg.com/prismjs/components/prism-json.min.js"></script>
<script src="http://unpkg.com/prismjs/components/prism-bash.min.js"></script>
<script src="http://unpkg.com/prismjs/components/prism-java.min.js"></script>
<script src="http://unpkg.com/prismjs/components/prism-markdown.min.js"></script>
<script src="http://unpkg.com/prismjs/components/prism-nginx.min.js"></script>
<script src="http://unpkg.com/prismjs/components/prism-php.min.js"></script>
<script src="http://unpkg.com/prismjs/components/prism-python.min.js"></script>
<script src="http://unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
<!-- docsify-themeable -->
<script src="https://unpkg.com/docsify-themeable"></script>
</body>
</html>
三逛犹、其它擴(kuò)展
搭建公司內(nèi)部文檔管理平臺(tái)，修改完畢后推送至遠(yuǎn)端自動(dòng)刷新虽画，考慮到時(shí)間問(wèn)題，后續(xù)再做詳細(xì)介紹喷鸽。
3.1依賴環(huán)境
Docsify灸拍、GitLab、Jenkins 版本無(wú)要求
3.2運(yùn)行環(huán)境
CentOS Linux release 7.3.1611
四混槐、培訓(xùn)目標(biāo)
通過(guò)本次內(nèi)部培訓(xùn)轩性，希望達(dá)成以下目標(biāo)：
（1）對(duì)docsify文檔管理有一定的了解和掌握；
（2）對(duì)MD文件的基本語(yǔ)法有一定的了解和掌握悯嗓；
（3）開發(fā)人員后期定義接口規(guī)范逐步使用docsify的方式進(jìn)行編寫卸察，文檔實(shí)時(shí)自動(dòng)刷新；
（4）對(duì)內(nèi)部的接口文檔管理等工作有一定的提高坑质；
