使用Docsify做文檔網站的詳細配置教程
- 2020 年 4 月 1 日
- 筆記
使用Docsify做文檔網站的詳細配置教程
作者：xhemj
沒錯，它叫Docsify。
xhemj的文檔中心就是用這個寫的
開源地址：https://github.com/docsifyjs/docsify/
官方Demo：https://docsify.js.org/
目錄
官方說明
Docsify A magical documentation site generator. Simple and lightweight (~21kB gzipped) No statically built html files Multiple themes Docsify
一個神奇的文檔站點生成器。
簡單輕巧（~21kB）
沒有生成靜態的html文件
主題豐富
安裝
本地搭建
如果你想在本地搭建：
npm安裝：
npm i docsify-cli -g 初始化：
docsify init ./docs 本地預覽：
docsify serve docs 進入http://localhost:3000就能看到效果咯！
託管在網上
如果你想在託管在網上：
新建一個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" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css"> </head> <body> <div id="app"></div> <script> window.$docsify = { //... } </script> <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script> </body> </html> CDN的選擇
CDN可以選擇：
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script> <script src="//cdnjs.cloudflare.com/ajax/libs/docsify/4.11.2/docsify.min.js"></script> <script src="//unpkg.com/docsify/lib/docsify.min.js"></script> 這樣就可以看到一個最基本的網頁啦！
如何寫文章
只需用Markdown語法寫好一個.md的文章放在根目錄或子目錄後就會自動識別了。
我自己測試好像用html的也可以，直接把後綴名改成.md，但效果可能不太好。
文章鏈接對應：
/README.md => domain.com/#/ /hello.md => domain.com/#/hello /hello/hi.md => domain.com/#/hello/hi 如本教程文章Markdown文件為：https://gitee.com/xhemj/books/raw/master/p/How-to-Use-Docsify.md
渲染成：https://xhemj.gitee.io/books/#/p/How-to-Use-Docsify
個性化
自定義載入文字
只需在index.html中新增：
<div id="app">Please wait...</div> 自定義側邊欄
只需在index.html中新增：
<script> window.$docsify = { loadSidebar: true } </script> 後創建一個文件叫做_sidebar.md，將你的文件輸入進去：
* [Home](/) * [Guide](guide.md) _sidebar.md的載入邏輯是從每層目錄下獲取文件，如果當前目錄不存在該文件則回退到上一級目錄。
例如當前路徑為/zh-cn/more-pages則從/zh-cn/_sidebar.md獲取文件，如果不存在則從/_sidebar.md獲取。
注意，如果是託管在網上，請在文件根目錄新增名叫
.nojekyll的空文件。
為了更好地SEO，您可以在每個文件後面自定義標題：
* [Home](/) * [Guide](guide.md "The greatest guide in the world") 默認情況下會自動根據文章標題生成目錄，如果不想要，可以再index.html中新增：
<script> window.$docsify = { loadSidebar: true, subMaxLevel: 2 } </script> subMaxLevel: 2表示只顯示h1~h2的標題，對應#和##。
如果你想忽略某個標題，則可以在文章中新增{docsify-ignore}：
# Getting Started ## Header {docsify-ignore} 如果想忽略全部的標題，則可以新增{docsify-ignore-all}：
# Getting Started {docsify-ignore-all} ## Header 表示忽略{docsify-ignore-all}下的全部標題
{docsify-ignore-all}和{docsify-ignore}在正文中都不會顯示
自定義導航欄
寫法一：
在index.html中新增：
<body> <nav> <a href="#/">EN</a> <a href="#/zh-cn/">中文</a> </nav> <div id="app"></div> </body> 所有路徑都必須用
#/來書寫
寫法二：
在根目錄新增_navbar.md文件：
寫法同_sidebar.md
* [En](/) * [chinese](/zh-cn/) 你也可以按照如下來寫多級導航欄：
* Getting started * [Quick start](quickstart.md) * [Writing more pages](more-pages.md) * [Custom navbar](custom-navbar.md) * [Cover page](cover.md) * Configuration * [Configuration](configuration.md) * [Themes](themes.md) * [Using plugins](plugins.md) * [Markdown configuration](markdown.md) * [Language highlight](language-highlight.md) _navbar.md的載入邏輯是從每層目錄下獲取文件，如果當前目錄不存在該文件則回退到上一級目錄。
例如當前路徑為/zh-cn/more-pages則從/zh-cn/_navbar.md獲取文件，如果不存在則從_navbar.md獲取。
封面
設置：
window.$docsify = { coverpage: true, } 後再根目錄創建_coverpage.md
輸入內容就可以顯示在封面了
效果見https://xhemj.gitee.io/books/
主題顏色
設置：
window.$docsify = { themeColor: '#c30aff', } #c30aff就是主題的顏色了
外鏈打開方式
設置：
window.$docsify = { externalLinkTarget: '_blank', } _blank表示在新標籤頁中打開
插件
表情插件
先在在index.html中新增：
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script> 我自己測試是我上面推薦的三個CDN都可以使用
即可輸入
:100: => ?
搜索插件
新增index.html：
<script> window.$docsify = { search: 'auto', search : [ '/', // => /README.md '/guide', // => /guide.md '/get-started', // => /get-started.md '/zh-cn/', // => /zh-cn/README.md ], search: { maxAge: 86400000, paths: [], placeholder: 'Type to search', placeholder: { '/zh-cn/': '搜索', '/': 'Type to search' }, noData: 'No Results!', noData: { '/zh-cn/': '找不到結果', '/': 'No Results' }, depth: 2, hideOtherSidebarContent: false, namespace: 'website-1', } } </script> <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script> 那我們來解釋一下：
1.指定搜索路徑
search: 'auto',表示是否搜索，默認是auto
或：
search : [ '/', // => /README.md '/guide', // => /guide.md '/get-started', // => /get-started.md '/zh-cn/', // => /zh-cn/README.md ], 如：/就表示README.md
guide表示/guide.md
設置後就表示只搜索這幾個目錄
2.maxAge: 86400000,到期時間（官方這麼說），不用改動
3.paths: [], 可以設置搜索的目錄，或設置auto或/，貌似和search:[]一樣？
4.搜索框的提示
placeholder: 'Type to search',
或：
placeholder: { '/zh-cn/': '搜索', '/': 'Type to search' }, 這樣可以設置中英文目錄的搜索框的提示
noData: 'No Results!',表示無結果時顯示的文字
或：
noData: { '/zh-cn/': '找不到結果', '/': 'No Results' }, 分別設置中英文
5.標題深度
depth: 2,（官方這麼解釋）可以設置為1-6
6.隱藏其他側邊欄內容
hideOtherSidebarContent: false,（官方這麼解釋）默認為false
7.避免搜索索引衝突
namespace: 'website-1',可以自己設置
同一域下的多個網站之間可以設置名稱
避免搜索索引衝突
其實有很多參數都不用設置
比如我的配置是：
search: 'auto', search: { maxAge: 86400000, paths: '/', placeholder: '搜索...', noData: '未找到結果，換個搜索詞試試？', namespace: 'XhemjBlog', }, Google Analytics
就是Google統計
直接新增：
<script> window.$docsify = { ga: 'UA-XXXXX-Y' } </script> <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script> ga: 'UA-XXXXX-Y'就是Google統計的編號
或：
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js" data-ga="UA-XXXXX-Y"></script> <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script> ga: 'UA-XXXXX-Y'=data-ga="UA-XXXXX-Y"
外鏈腳本插件
如果你需要在.md文件中引用如：
<script src="https://domain.com/xxx.js" ></script> 安裝：
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script> 照這樣看來是可以在
.md中寫.html的……
圖片縮放插件
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script> 效果就是點擊一下圖片可以放大
如：
如果不想縮放可以設置：
 複製程式碼插件
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script> 效果可以自己看上面的所有程式碼
Disqus評論插件
<script> window.$docsify = { disqus: 'shortname' } </script> <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/disqus.min.js"></script> Gitalk評論插件
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/gitalk/dist/gitalk.css"> <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/gitalk.min.js"></script> <script src="//cdn.jsdelivr.net/npm/gitalk/dist/gitalk.min.js"></script> <script> var 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> 可以使文章實現評論效果，教程詳見：https://github.com/gitalk/gitalk/
鏈接下一篇文章插件
可以再文章底部顯示「下一篇」和「上一篇」
效果見https://xhemj.gitee.io/books/#/p/how-to-use-Docsify.md
<script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script> 也可以自定義：
window.$docsify = { pagination: { previousText: '上一篇', nextText: '下一篇', crossChapter: true, crossChapterText: true, }, } 更多插件可以見https://docsify.js.org/#/awesome?id=plugins
以下是我自己使用的插件
Social Share分享插件
經過測試，無法直接在index.html中嵌入程式碼
需要先安裝上面的外鏈腳本插件
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script> 後在.md文件中寫下：
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/social-share.js/1.0.16/css/share.min.css"> <div class="social-share"></div> <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/social-share.js/1.0.16/js/social-share.min.js"></script> 即可在文件中嵌入分享插件
詳細自定義教程可見：https://github.com/overtrue/share.js
嵌入Markdown文件插件
<script src="https://unpkg.com/docsify-remote-markdown/dist/docsify-remote-markdown.min.js"> 可以自定義：
window.$docsify = { remoteMarkdown: { tag: 'md', }, } 使用方法：
[你設置的tag，如：md](https://domain.com/markdown.md) 效果如上方的分享插件就可以直接鏈接：
而不用寫分享程式碼
<script src="https://unpkg.com/docsify-footer-enh/dist/docsify-footer-enh.min.js"></script> 自定義：
window.$docsify = { footer: { copy: '', auth: '', pre: '<hr>', style:'text-align: center;' }, } 實測copy和auth可以隨便寫
寫什麼文字程式碼都可以
pre是正文和Footer的分割線，默認<hr>
效果可以見https://xhemj.gitee.io/books/#/p/how-to-use-Docsify.md
結尾
基本上配置就是這樣了！本文當基於官方文檔書寫
要是有什麼說不到位的歡迎私信我或者發郵件到xhemj2680@163.com哦！
好看就分享一下吧！
