tags: docsify doc github
1.引言
在軟件開發(fā)過(guò)程中欲侮，編程人員經(jīng)常需要寫文檔臀稚，如開發(fā)文檔吝岭、接口文檔、使用手冊(cè)等吧寺，也會(huì)經(jīng)常編寫blog記錄開發(fā)過(guò)程窜管，技術(shù)感悟。對(duì)于這些文檔稚机，一般情況下編寫人員有以下幾種需求：編寫簡(jiǎn)單幕帆、對(duì)外發(fā)布、格式友好赖条、形式專業(yè)失乾。而編寫的工具則有好多，包括以下幾類：
- word工具類：如office word纬乍，wps,txt等
- 平臺(tái)博客類：csdn碱茁，簡(jiǎn)書，oschina等
- 自建網(wǎng)站類：github仿贬，hexo纽竣，gitbook，markdown等
- 知識(shí)工具類：confluence，語(yǔ)雀蜓氨，看云等
當(dāng)然聋袋，各種工具有各自的優(yōu)缺點(diǎn)，簡(jiǎn)單一點(diǎn)的話语盈，使用語(yǔ)雀舱馅、看云來(lái)寫長(zhǎng)系列文章或者書籍也比較適合，但作為一個(gè)開發(fā)人員刀荒，希望找一個(gè)能屬于自己的代嗤，簡(jiǎn)單的，有點(diǎn)逼格的文檔工具缠借，特別是針對(duì)開源軟件文檔編寫干毅，放個(gè)pdf或者doc文檔，不便于維護(hù)泼返，格調(diào)也不夠高硝逢，最好能跟github關(guān)聯(lián)，即時(shí)可看绅喉，又方便維護(hù)渠鸽，如此，則非docsify莫屬了（當(dāng)然gitboot也行）柴罐。如下可以截圖看一下基于docsify構(gòu)建的文檔徽缚。本文針對(duì)如何使用docsify實(shí)現(xiàn)文檔構(gòu)建進(jìn)行講解，希望能幫助到想構(gòu)建自己的文檔網(wǎng)站的同學(xué)革屠。
2.docsify簡(jiǎn)介
按docsify官網(wǎng)的介紹凿试，一句話:一個(gè)神奇的文檔網(wǎng)站生成工具，使用它似芝，可以使用簡(jiǎn)單的方式那婉，構(gòu)建一個(gè)專業(yè)的文檔網(wǎng)站。如果使用過(guò)GitBook和Hexo的同學(xué)党瓮，可以知識(shí)它們使用markdown編寫文檔详炬，然后轉(zhuǎn)為html進(jìn)行顯示。而docsify 是一個(gè)動(dòng)態(tài)生成文檔網(wǎng)站的工具寞奸。不同于 GitBook痕寓、Hexo 的地方是它不會(huì)生成將 .md 轉(zhuǎn)成 .html 文件，所有轉(zhuǎn)換工作都是在運(yùn)行時(shí)進(jìn)行蝇闭。只需要?jiǎng)?chuàng)建一個(gè) index.html 呻率，就可以開始寫文檔而且直接部署在 GitHub Pages進(jìn)行發(fā)布，方便呻引、快捷礼仗、格式友好，樣式不錯(cuò)。
3. 使用docsify構(gòu)建文檔
本章節(jié)將對(duì)如何使用docsify構(gòu)建文檔進(jìn)行詳細(xì)描述元践。
3.1 構(gòu)建docsify目錄結(jié)構(gòu)
3.1.1 目錄結(jié)構(gòu)
docsify有其規(guī)范的目錄結(jié)構(gòu)韭脊，創(chuàng)建一個(gè)目錄，如test单旁，目錄下最基本的結(jié)構(gòu)如下：
-
index.html： 入口文件 -
README.md： 會(huì)做為主頁(yè)內(nèi)容渲染 -
.nojekyll： 用于阻止 GitHub Pages 會(huì)忽略掉下劃線開頭的文件
若在本地測(cè)試沪羔，.nojekyll可不需要，若發(fā)布到Github Pages象浑，則需要此文件蔫饰。
3.1.2 編寫index.html
index.html
<!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>
注意
此處使用在線引入docsify的js，如//unpkg.com/docsify/lib/docsify.min.js愉豺，用戶也可以直接下載此文件到本地篓吁，進(jìn)行本地引用。
3.1.3 編寫README.MD
文檔內(nèi)容均以markdown的方式編寫蚪拦，README.MD作為文檔的首頁(yè)杖剪，如下是README.MD的內(nèi)容
## 我是首頁(yè)
這是我的首頁(yè)介紹
3.1.4 修改logding提示
初始化時(shí)會(huì)顯示 Loading... 內(nèi)容，可以自定義提示信息驰贷。修改index.html的app的div中的文字即可盛嘿，如下：
<div id="app">加載中...</div>
3.1.5 本地預(yù)覽網(wǎng)站
最方便的就是本地安裝一個(gè)python(不會(huì)安裝的請(qǐng)百度)，然后使用Python來(lái)啟動(dòng)一個(gè)服務(wù)括袒，對(duì)于python3次兆，在此目錄下運(yùn)行以下命令即可啟動(dòng)：
python -m http.server 3000
3000是開啟的端口號(hào)，用戶可自行定義箱熬，啟動(dòng)后类垦，出現(xiàn)以下提示：
Serving HTTP on 0.0.0.0 port 3000 (http://0.0.0.0:3000/) ...則表示啟動(dòng)成功狈邑。使用瀏覽器訪問(wèn)localhost:3000即可訪問(wèn)文檔城须。如下：
至此，已經(jīng)完成最基本的文檔網(wǎng)站了米苹，若是把完整的文檔寫在README.MD中糕伐，文檔也基本完成了，可以正常顯示蘸嘶。修改文檔和index.html后良瞧，刷新頁(yè)面即可顯示更新。
3.1.6 使用docsify-cli創(chuàng)建
若已安裝nodejs训唱，則可以不手動(dòng)創(chuàng)建上面的文件褥蚯，使用npm安裝docsify-cli，創(chuàng)建目錄况增，然后使用docsify init ./赞庶，它完成的工作與前面手動(dòng)生成的文件是一致的。具體可參考官方文檔。
3.2 設(shè)置文檔側(cè)邊欄
如前面示例歧强，默認(rèn)情況下澜薄，文檔側(cè)邊欄會(huì)根據(jù)當(dāng)前文檔的標(biāo)題生成目錄，且會(huì)把目錄全部展開摊册。如下所示：
但一般我們寫文檔或書籍肤京，都習(xí)慣把長(zhǎng)文檔分章節(jié)編寫（即每章節(jié)一個(gè)文件），然后顯示時(shí)目錄可折疊茅特，更方便閱讀忘分。docsify則提供了多文檔側(cè)邊欄的定制。
3.2.1 設(shè)置多文檔側(cè)邊欄
假設(shè)文檔結(jié)構(gòu)（書結(jié)構(gòu)）如下：
版權(quán)信息
序
第一篇
-- 第1章
-- 1.1 xxx
-- 1.2 xxx
-- 第2章
第二篇
...
對(duì)應(yīng)的文件如下（注意：由于docsify是根據(jù)路徑作為url訪問(wèn)的温治，目錄名及文件名不要使用中文或空格）：
.
├── a
│ ├── 1.md
│ └── 2.md
├── b
├── copyright.md
├── index.html
├── preface.md
└── README.md
只需要兩步即可完成側(cè)邊欄設(shè)置：
- (1) 在
index.html文件中的window.$docsify添加loadSidebar: true,選項(xiàng)：
<script>
window.$docsify = {
loadSidebar: true
}
</script>
<script src="http://unpkg.com/docsify"></script>
- (2) 根目錄創(chuàng)建
_sidebar.md文件
編寫目錄內(nèi)容饭庞，有鏈接內(nèi)容則使用[xx](yy)格式，xx是顯示內(nèi)容熬荆，yy是連接地址舟山，連接地址以index.html所在目錄為當(dāng)前目錄，連接到對(duì)應(yīng)文件的路徑卤恳，文件后綴md省略累盗。有層次結(jié)構(gòu)的使用空格分隔層次。如下：
* [版權(quán)信息](copyright)
* [序](preface)
* 第一篇
* [第1章](a/1)
* [第2章](a/2)
* 第二篇
* [第3章](b/3)
設(shè)置完成后突琳，刷新頁(yè)面若债，顯示結(jié)果如下：
3.2.2 設(shè)置章節(jié)目錄顯示
上述定制的側(cè)邊欄僅根據(jù)_sidebar.md文件顯示了頁(yè)面大框架的鏈接，但各章節(jié)所在的目錄(標(biāo)題)沒(méi)有顯示拆融，需要在index.html文件中的window.$docsify添加subMaxLevel字段來(lái)設(shè)置：
<script>
window.$docsify = {
loadSidebar: true,
subMaxLevel: 3
}
</script>
<script src="http://unpkg.com/docsify"></script>
設(shè)置后蠢琳，效果如下：
注意：subMaxLevel類型是number(數(shù)字)，表示顯示的目錄層級(jí)
如果md文件中的第一個(gè)標(biāo)題是一級(jí)標(biāo)題镜豹，那么不會(huì)顯示在側(cè)邊欄傲须，如上圖所示
3.2.3 忽略頁(yè)面標(biāo)題在側(cè)邊欄目錄顯示
注意： 如果md文件的第一個(gè)標(biāo)題是一級(jí)標(biāo)題，那么默認(rèn)已經(jīng)忽略了趟脂。
當(dāng)設(shè)置了 subMaxLevel 時(shí)泰讽，默認(rèn)情況下每個(gè)標(biāo)題都會(huì)自動(dòng)添加到目錄中。如果你想忽略特定的標(biāo)題昔期，可以給它添加 {docsify-ignore} ：
# Getting Started
## Header {docsify-ignore}
該標(biāo)題不會(huì)出現(xiàn)在側(cè)邊欄的目錄中已卸。
要忽略特定頁(yè)面上的所有標(biāo)題，你可以在頁(yè)面的第一個(gè)標(biāo)題上使用{docsify-ignore-all} :
# Getting Started {docsify-ignore-all}
## Header
該頁(yè)面所有標(biāo)題都不會(huì)出現(xiàn)在側(cè)邊欄的目錄中硼一。
3.3 設(shè)置封面
docsify默認(rèn)是沒(méi)有封面的累澡，默認(rèn)有個(gè)首頁(yè)./README.md。通過(guò)設(shè)置coverpage參數(shù)般贼，可以開啟渲染封面的功能愧哟。
首先需要在index.html文件中的window.$docsify添加coverpage: true選項(xiàng)：
<script>
window.$docsify = {
coverpage: true
}
</script>
<script src="http://unpkg.com/docsify"></script>
接著在項(xiàng)目根目錄創(chuàng)建_coverpage.md文件惑申，內(nèi)容格式如下：
# 我的文檔網(wǎng)站
## 個(gè)人文檔網(wǎng)站
> 一個(gè)神奇的文檔網(wǎng)站生成鞏固
* Simple and lightweight (~12kb gzipped)
* Multiple themes
* Not build static html files
[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#quick-start)
[Get Started](#quick-start)
目前的背景是隨機(jī)生成的漸變色，每次刷新都會(huì)顯示不同的顏色翅雏。docsify封面支持自定義背景色或者背景圖圈驼，在_coverpage.md文檔末尾添加：
<!-- 背景圖片 -->
<!-- 背景色 -->
注意：
1.自定義背景配置一定要在_coverpage.md文檔末尾。
2.背景圖片和背景色只能有一個(gè)生效.
3.背景色一定要是#fbb30b這種格式的望几。
4.icon.svg和bg.png需要自己創(chuàng)建并放到_media目錄下
設(shè)置封面后绩脆，效果如下：
3.4 編寫markdown內(nèi)容
如上述示例，文本內(nèi)容都是使用markdown進(jìn)行編寫橄抹，關(guān)于markdown的編寫規(guī)范靴迫，可參考官方文檔。markdown的編寫工具有很多楼誓，熟練的可以直接使用文本進(jìn)行編輯玉锌，中文的markdown工具有Typora，cmdMarkdown疟羹，有道云筆記等等主守。
3.5 選擇主題樣式
docsify默認(rèn)提供了不同的主題樣式，默認(rèn)是vue.css榄融。用戶可以根據(jù)自己需要來(lái)使用即可参淫。
<link rel="stylesheet" >
<link rel="stylesheet" >
<link rel="stylesheet" >
<link rel="stylesheet" >
<link rel="stylesheet" >
還有一些第三方的主題樣式，如：
#示例地址：
https://jhildenbiddle.github.io/docsify-themeable/#/customization
#引入方法：
link rel="stylesheet" >
3.6 添加搜索功能
一般文章提供搜索功能是比較人性化的功能愧杯，在docsify中添加搜索功能涎才，只需要在index.html添加search插件，然后在window.$docsify添加search參數(shù)即可力九。如下：
window.$docsify = {
search: {
maxAge: 86400000, // 過(guò)期時(shí)間耍铜，單位毫秒，默認(rèn)一天
noData: '找不到結(jié)果',//搜索不到結(jié)果時(shí)顯示
paths: 'auto',//自動(dòng)
placeholder: '搜索',//搜索框提示
},
}
<script src="http://unpkg.com/docsify/lib/plugins/search.js"></script>
具體參數(shù)設(shè)置可參考官網(wǎng)
添加搜索功能后跌前，效果如下：
4. 總結(jié)
本篇文章介紹了docsify的優(yōu)點(diǎn)棕兼，并對(duì)使用docsify構(gòu)建文檔網(wǎng)站的步驟進(jìn)行說(shuō)明，分別是：引入docsify文件 -> 設(shè)置目錄框架 -> 編寫markdown內(nèi)容 -> 設(shè)置封面/樣式 -> 添加搜索功能舒萎。然后使用python啟動(dòng)（當(dāng)然也可以使用其它web服務(wù)器如nginx,apache）提供靜態(tài)網(wǎng)站服務(wù)即可程储。希望對(duì)有需要的同學(xué)有所幫助蹭沛。
5.參考資料
- docsify官網(wǎng)： https://docsify.js.org
- docsify教程： https://segmentfault.com/a/1190000017576714
- markdown官網(wǎng)：http://www.markdown.cn/
