docsify 是一個(gè)動(dòng)態(tài)生成文檔網(wǎng)站的工具诅岩。不同于 GitBook讳苦、Hexo 的地方是它不會(huì)生成將 .md 轉(zhuǎn)成 .html 文件带膜，所有轉(zhuǎn)換工作都是在運(yùn)行時(shí)進(jìn)行。
這將非常實(shí)用鸳谜，如果只是需要快速的搭建一個(gè)小型的文檔網(wǎng)站膝藕，或者不想因?yàn)樯傻囊欢?.html 文件“污染” commit 記錄，只需要?jiǎng)?chuàng)建一個(gè) index.html 就可以開始寫文檔而且直接部署在 GitHub Pages咐扭。
特性
- 無需構(gòu)建芭挽，寫完文檔直接發(fā)布
- 容易使用并且輕量 (~19kB gzipped)
- 智能的全文搜索
- 提供多套主題
- 豐富的 API
- 支持 Emoji
- 兼容 IE10+
- 支持 SSR (example)
快速開始
推薦安裝 docsify-cli 工具，可以方便創(chuàng)建及本地預(yù)覽文檔網(wǎng)站蝗肪。
npm i docsify-cli -g
初始化項(xiàng)目
如果想在項(xiàng)目的 ./docs 目錄里寫文檔袜爪，直接通過 init 初始化項(xiàng)目。
docsify init ./docs
開始寫文檔
初始化成功后薛闪，可以看到 ./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è)面。
本地預(yù)覽網(wǎng)站
運(yùn)行一個(gè)本地服務(wù)器通過 docsify serve 可以方便的預(yù)覽效果豁延，而且提供 LiveReload 功能昙篙，可以讓實(shí)時(shí)的預(yù)覽。默認(rèn)訪問 http://localhost:3000 诱咏。
docsify serve docs
更多命令行工具用法苔可，參考 docsify-cli 文檔。
手動(dòng)初始化
如果不喜歡 npm 或者覺得安裝工具太麻煩袋狞，我們其實(shí)只需要直接創(chuàng)建一個(gè) 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>
如果系統(tǒng)里安裝 Python 的話，也可以很輕易的啟動(dòng)一個(gè)靜態(tài)服務(wù)器苟鸯。
cd docs && python -m SimpleHTTPServer 3000
Loading 提示
初始化時(shí)會(huì)顯示 Loading... 內(nèi)容法焰，你可以自定義提示信息。
// index.html
<div id="app">加載中</div>
如果更改了 el 的配置倔毙，需要將該元素加上 data-app 屬性埃仪。
// index.html
<div data-app id="main">加載中</div>
<script>
window.$docsify = {
el: '#main'
}
</script>
示例
這是一份docsify開發(fā)的文檔歡迎點(diǎn)擊查看
更加詳細(xì)的設(shè)置配置參考官方文檔
