docsify網站文件工具用法總結
阿新 • • 發佈:2019-01-11
docsify , 網站文件動態生成工具,類似gitbook
特性
- 無需構建,寫完文件直接釋出
- 容易使用並且輕量 (~19kB gzipped)
- 智慧的全文搜尋
- 提供多套主題
- 豐富的 API
- 支援 Emoji
- 相容 IE10+
- 支援 SSR
安裝
npm i docsify-cli -g
進入專案根目錄並初始化
docsify init ./docs
之後docs目錄下會生成以下幾個檔案
index.html 入口檔案 README.md 會做為主頁內容渲染 .nojekyll 用於阻止 GitHub Pages 會忽略掉下劃線開頭的檔案
執行服務
docsify serve ./docs
開啟瀏覽器 http://localhost:3000
多頁文件
建立多個頁面,或者多級路由。建立一個 guide.md 檔案,那麼對應的路由就是 /#/guide。
例如這樣一個目錄結構
-| docs/ -| README.md -| guide.md -| zh-cn/ -| README.md -| guide.md docs/README.md => http://domain.com docs/guide.md => http://domain.com/guide docs/zh-cn/README.md => http://domain.com/zh-cn/ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide
設定封面
設定 coverpage 引數
window.$docsify = {
coverpage: true
}
接著在根目錄建立 _coverpage.md 檔案
背景自定義
預設的背景是隨機生成的漸變色
如要自定義背景圖片或者背景色,在_coverpage.md中設定如下內容
<!-- 背景圖片 -->
![](_media/bg.png)
<!-- 背景色 -->
![color](#f0f0f0)
自定義導航欄
直接在 HTML 裡定義導航欄,連結以 #/ 開頭
在index.html的body中新增以下程式碼
<nav> <a href="#/">EN</a> <a href="#/zh-cn/">中文</a> </nav> <div id="app"></div>
接著配置 loadNavbar
window.$docsify = {
loadNavbar: true
}
在navbar.md_中新增以下連結
* [En](/)
* [中文](/zh-cn/)
側邊欄導航
預設側邊欄會根據當前文件的標題生成目錄。也可以設定文件連結,通過 Markdown 檔案生成
先配置 loadSidebar 選項
window.$docsify = {
loadSidebar: true
}
然後建立 _sidebar.md 檔案,這樣我們左側目錄就會顯示出來
* [首頁](zh-cn/)
* [指南](zh-cn/guide)
需要在文件根目錄建立 .nojekyll 命名的空檔案,阻止 GitHub Pages 忽略命名是下劃線開頭的檔案。
外掛
新增全文搜尋
引入search.js
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
配置search選項
search: {
maxAge: 86400000, // 過期時間,單位毫秒,預設一天
paths: [], // or 'auto'
placeholder: 'Type to search',
// 支援本地化
placeholder: {
'/zh-cn/': '搜尋',
'/': 'Type to search'
},
noData: 'No Results!',
// 支援本地化
noData: {
'/zh-cn/': '找不到結果',
'/': 'No Results'
},
// 搜尋標題的最大程級, 1 - 6
depth: 2
}
新增評論系統
Gitalk,一個現代化的,基於Preact和Github Issue的評論系統。
<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">
<script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
<script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
<script>
const gitalk = new Gitalk({
clientID: 'Github Application Client ID',
clientSecret: 'Github Application Client Secret',
repo: 'Github repo',
owner: 'Github repo owner',
admin: ['Github repo collaborators, only these guys can initialize github issues'],
// facebook-like distraction free mode
distractionFreeMode: false
})
</script>
clientID和clientSecret需要在github上建立一個app生成