簡介
一個神奇的文檔網(wǎng)站生成工具
我們在做完項目的時候經(jīng)常會寫一些項目手冊，來記錄我們在項目開發(fā)過程中的一些開發(fā)流程、使用方式以及注意事項，分享給將會使用到這個項目的人，方便大家快速上手，讓程序順利運(yùn)行。
目前比較好的方式就是寫成Markdown格式的技術(shù)文檔，方便我們發(fā)布在github上，同時也可以發(fā)布到博客分享平臺。除此之外我們還可以借助docsify這個工具，來幫助我們快速的搭建一個小型的文檔網(wǎng)站，它可以自動將我們寫在Markdown中的標(biāo)題生成目錄，整個頁面的配色和布局也十分舒適易讀，讓整個閱讀體驗提升了好幾個level，有了docsify這個神器，再也不害怕看長長的技術(shù)文檔了。
docsify 是一個動態(tài)生成文檔網(wǎng)站的工具。不同于 GitBook、Hexo 的地方是它不會將 .md 轉(zhuǎn)成 .html 文件，所有轉(zhuǎn)換工作都是在運(yùn)行時進(jìn)行。這將非常實用，如果只是需要快速的搭建一個小型的文檔網(wǎng)站，或者不想因為生成的一堆 .html 文件“污染” commit 記錄，只需要創(chuàng)建一個 index.html 就可以開始寫文檔而且直接部署在GitHub Pages。
先看一些使用docsify生成的技術(shù)文檔：
它的docsify中文官方文檔就是利用docsify生成的，展示效果一目了然。
這是我用docsify生成的豆瓣影音項目文檔：https://hanxueqing.github.io/Douban-Movie/
特性
- 無需構(gòu)建，寫完文檔直接發(fā)布
- 容易使用并且輕量 (~19kB gzipped)
- 智能的全文搜索
- 提供多套主題
- 豐富的 API
- 支持 Emoji
- 兼容 IE10+
- 支持 SSR (example)
快速安裝
1. 全局安裝docsify
npm i docsify-cli -g
安裝成功后顯示
2. 初始化項目
docsify init ./docs
初始化成功后，可以看到 ./docs 目錄下創(chuàng)建的幾個文件
index.html 入口文件
README.md 會做為主頁內(nèi)容渲染
.nojekyll 用于阻止 GitHub Pages 會忽略掉下劃線開頭的文件
直接編輯 docs/README.md 就能更新網(wǎng)站內(nèi)容，當(dāng)然也可以寫多個頁面。
3. 本地預(yù)覽網(wǎng)站
運(yùn)行一個本地服務(wù)器，通過 docsify serve 可以方便的預(yù)覽效果，而且提供 LiveReload 功能，可以實時的預(yù)覽。默認(rèn)通過 http://localhost:3000訪問。
docsify serve docs
常用配置項
Github Corner
通過設(shè)置index.html中window.$docsify的 repo 參數(shù)配置倉庫地址或者 username/repo 的字符串，會在頁面右上角渲染一個 GitHub Corner 掛件，點擊即可跳轉(zhuǎn)到Github中對應(yīng)的項目地址。
<script>
window.$docsify = {
name: '豆瓣影音',
repo: 'https://github.com/Hanxueqing/Douban-Movie.git',
coverpage: true
}
</script>
封面
通過設(shè)置index.html中window.$docsify的 coverpage 參數(shù)，即可開啟渲染封面的功能。
<script>
window.$docsify = {
name: '豆瓣影音',
repo: '',
coverpage: true
}
</script>
封面的生成同樣是從 markdown 文件渲染來的。開啟渲染封面功能后在文檔根目錄創(chuàng)建 _coverpage.md 文件，在文檔中編寫需要展示在封面的內(nèi)容。
# 豆瓣影音
> 使用Vue全家桶+Node.js搭建的小型全棧項目.
* 前端框架：vue-cli、vue-router、axios、vuex
* UI類庫：Mint-UI、Vant
* 后端數(shù)據(jù)接口：Express、MongoDB
[GitHub](https://github.com/Hanxueqing/Douban-Movie.git)
[Get Started](#quick-start)
展示效果如圖：
目前的背景是隨機(jī)生成的漸變色，我們自定義背景色或者背景圖?？梢詤⒖脊倬W(wǎng)文檔封面這一章節(jié)自行設(shè)置。
主題
直接打開 index.html 修改替換 css 地址即可切換主題，官方目前提供五套主題可供選擇，模仿 Vue 和 buble 官網(wǎng)訂制的主題樣式。還有 @liril-net 貢獻(xiàn)的黑色風(fēng)格的主題。
<link rel="stylesheet" >
<link rel="stylesheet" >
<link rel="stylesheet" >
<link rel="stylesheet" >
<link rel="stylesheet" >
其他主題docsify-themeable又提供了三種樣式可供選擇：
docsify-themeable是一個用于docsify的，簡單到令人愉悅的主題系統(tǒng).
<!-- Theme: Defaults -->
<link rel="stylesheet" >
<!-- Theme: Defaults -->
<link rel="stylesheet" >
<!-- Theme: Simple Dark -->
<link rel="stylesheet" >
另外還有一種在網(wǎng)上看到的樣式：
<link rel="stylesheet" >
多頁面
目前我創(chuàng)建的文檔是單頁面的，上下滾動即可瀏覽全部內(nèi)容。如果想創(chuàng)建多個頁面，即點擊左側(cè)側(cè)邊欄導(dǎo)航跳轉(zhuǎn)到不同url，就需要配置多級路由，這一功能在docsify中也很容易實現(xiàn)，我們需要在index.html文件中的window.$docsify中開啟loadSidebar選項：
<script>
window.$docsify = {
loadSidebar: true
}
</script>
<script src="http://unpkg.com/docsify"></script>
然后在根目錄創(chuàng)建自己的_sidebar.md文件，配置我們需要顯示的頁面。詳細(xì)操作步驟參考官方多頁文檔教程。
注：配置了loadSidebar后就不會生成默認(rèn)的側(cè)邊欄了。
插件
官方還提供了非常多實用的插件，比如說全文搜索、解析emoji表情、一鍵復(fù)制代碼等等，完整版請參考官方插件列表。
Github Pages
和 GitBook 生成的文檔一樣，我們可以直接把文檔網(wǎng)站部署到 GitHub Pages 或者 VPS 上。
GitHub Pages 支持從三個地方讀取文件
-
docs/目錄 - master 分支
- gh-pages 分支
我們推薦直接將文檔放在 docs/ 目錄下，找到倉庫的Settings設(shè)置頁面
開啟 GitHub Pages 功能并選擇 master branch /docs folder 選項。
發(fā)布成功后會顯示網(wǎng)站地址，通過這個地址即可在線訪問你編寫的技術(shù)文檔了。
