使用Docsify做文檔網(wǎng)站的詳細配置教程
作者：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）
沒有生成靜態(tài)的html文件
主題豐富
安裝
本地搭建
如果你想在本地搭建：
npm安裝：
npm i docsify-cli -g
初始化：
docsify init ./docs
本地預覽：
docsify serve docs
進入http://localhost:3000就能看到效果咯栽惶！
托管在網(wǎng)上
如果你想在托管在網(wǎng)上：
新建一個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://cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>
CDN的選擇
CDN可以選擇：
<script src="http://cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="http://cdnjs.cloudflare.com/ajax/libs/docsify/4.11.2/docsify.min.js"></script>
<script src="http://unpkg.com/docsify/lib/docsify.min.js"></script>
這樣就可以看到一個最基本的網(wǎng)頁啦涂身！
如何寫文章
只需用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>
后創(chuàng)建一個文件叫做_sidebar.md，將你的文件輸入進去：
* [Home](/)
* [Guide](guide.md)
_sidebar.md的加載邏輯是從每層目錄下獲取文件诺祸，如果當前目錄不存在該文件則回退到上一級目錄携悯。
例如當前路徑為/zh-cn/more-pages則從/zh-cn/_sidebar.md獲取文件，如果不存在則從/_sidebar.md獲取筷笨。
注意憔鬼，如果是托管在網(wǎng)上龟劲，請在文件根目錄新增名叫
.nojekyll的空文件。
為了更好地SEO轴或，您可以在每個文件后面自定義標題：
* [Home](/)
* [Guide](guide.md "The greatest guide in the world")
默認情況下會自動根據(jù)文章標題生成目錄昌跌，如果不想要，可以再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,
}
后再根目錄創(chuàng)建_coverpage.md
輸入內容就可以顯示在封面了
效果見https://xhemj.gitee.io/books/
主題顏色
設置：
window.$docsify = {
themeColor: '#c30aff',
}
#c30aff就是主題的顏色了
外鏈打開方式
設置：
window.$docsify = {
externalLinkTarget: '_blank',
}
_blank表示在新標簽頁中打開
插件
表情插件
先在在index.html中新增：
<script src="http://cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
我自己測試是我上面推薦的三個CDN都可以使用
即可輸入
:100: => :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="http://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',可以自己設置
同一域下的多個網(wǎng)站之間可以設置名稱
避免搜索索引沖突
其實有很多參數(shù)都不用設置
比如我的配置是：
search: 'auto',
search: {
maxAge: 86400000,
paths: '/',
placeholder: '搜索...',
noData: '未找到結果静浴，換個搜索詞試試？',
namespace: 'XhemjBlog',
},
Google Analytics
就是谷歌統(tǒng)計
直接新增：
<script>
window.$docsify = {
ga: 'UA-XXXXX-Y'
}
</script>
<script src="http://cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>
ga: 'UA-XXXXX-Y'就是谷歌統(tǒng)計的編號
或：
<script src="http://cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js" data-ga="UA-XXXXX-Y"></script>
<script src="http://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="http://cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script>
照這樣看來是可以在
.md中寫.html的……
圖片縮放插件
<script src="http://cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
效果就是點擊一下圖片可以放大
如：
[圖片上傳失敗...(image-349c4a-1585716054611)]
如果不想縮放可以設置：
復制代碼插件
<script src="http://cdn.jsdelivr.net/npm/docsify-copy-code"></script>
效果可以自己看上面的所有代碼
Disqus評論插件
<script>
window.$docsify = {
disqus: 'shortname'
}
</script>
<script src="http://cdn.jsdelivr.net/npm/docsify/lib/plugins/disqus.min.js"></script>
Gitalk評論插件
<link rel="stylesheet" >
<script src="http://cdn.jsdelivr.net/npm/docsify/lib/plugins/gitalk.min.js"></script>
<script src="http://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>
可以使文章實現(xiàn)評論效果挤渐，教程詳見：https://github.com/gitalk/gitalk/
鏈接下一篇文章插件
可以再文章底部顯示“下一篇”和“上一篇”
效果見https://xhemj.gitee.io/books/#/p/how-to-use-Docsify.md
<script src="http://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分享插件
經(jīng)過測試苹享，無法直接在index.html中嵌入代碼
需要先安裝上面的外鏈腳本插件
<script src="http://cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script>
后在.md文件中寫下：
<link rel="stylesheet" >
<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
結尾
基本上配置就是這樣了得问！本文當基于官方文檔書寫
要是有什么說不到位的歡迎私信我或者發(fā)郵件到xhemj2680@163.com哦！
好看就分享一下吧软免！
