docsify
根据官方说法，docsify是一个神奇的文档网站生成工具，也可以把它当做一个简易版的静态站点诸如Hexo、Hugo等。当然，它是专门针对文档的，忽然想到了程序员深恶痛绝的就是写API文档……
docsify特性很多，最吸引我的是全文搜索、主题简洁好看、无需构建的纯静态站点。这意味着可以很简单地把写完的文档直接扔到Pages服务上，比如GitHub Pages、Coding Pages等等。
快速安装
首先需要先安装npm，这里简单说下。安装npm之前需要先安装node.js，而博主是Windows系统，可以通过nvm-windows来安装node.js，具体可以参考这篇文章
然后用npm来全局安装docsify：
简易搭建
初始化
创建一个文档站点目录，比如note目录，然后在该目录下执行命令：
然后docsify会在该目录下新建一个docs目录，里面有3个初始文件：
.nojekyll：告诉GitHub Pages服务该站点不使用Jekyll作为构建工具index.html：入口文件README.md：作为首页渲染
请尽量使用docs目录来初始化docsify，原因是后面要用该目录部署到GitHub Pages。
本地预览与实时更新
使用如下命令可以本地预览站点：
然后就可以通过http://localhost:3000/来访问你的文档站点。
docsify支持实时更新，可以在启动本地服务时自动重新加载刚刚更新的文件。
常用配置
站点标题、图标
站点标题需要修改index.html里的title标签：
1
| <title>Java-Note</title>
|
站点图标要在index.html添加如下代码：
1
| <link rel="icon" href="//cdn.jsdelivr.net/gh/lewky/lewky.github.io@master/images/avatar.jpg">
|
主题选择
docsify提供了多款主题，通过修改index.html里的css地址即可更换主题：
1
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
|
还有以下的主题可以挑选，有遗漏的可以帮忙补充下：
1
2
3
4
5
6
7
8
9
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/buble.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/dark.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/pure.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/dolphin.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">
|
Github Corner
index.html里有个脚本代码如下：
1
2
3
4
5
6
| <script>
window.$docsify = {
name: '',
repo: ''
}
</script>
|
name会作为标题显示在站点的侧边栏，repo会作为Github Corner显示在站点的右上角，点击可跳转到对应的地址。样例如下：
1
2
3
4
5
6
| <script>
window.$docsify = {
name: 'Java-Note',
repo: 'https://github.com/lewky'
}
</script>
|
coverpage封面
该参数可以给站点添加一个封面，如下：
1
2
3
4
5
6
7
| <script>
window.$docsify = {
name: 'Java-Note',
repo: 'https://github.com/lewky',
coverpage: true
}
</script>
|
封面由_coverpage.md来渲染，默认无该文件需自行创建，内容如下：
1
2
3
4
5
6
7
8
9
| 
# Java笔记
> 个人向的Java学习笔记
* 贵在坚持
[开始阅读](/README)
|
loadNavbar导航栏
该参数用于添加导航栏，如下：
1
2
3
4
5
6
7
| <script>
window.$docsify = {
name: 'Java-Note',
repo: 'https://github.com/lewky',
loadNavbar: true
}
</script>
|
同样需要新建文件_navbar.md，内容如下：
1
2
3
| * [Home](/)
* Links
* [CS-Notes](http://cyc2018.gitee.io/cs-notes/#/README)
|
该参数用于添加侧边栏，如下：
1
2
3
4
5
6
7
| <script>
window.$docsify = {
name: 'Java-Note',
repo: 'https://github.com/lewky',
loadSidebar: true
}
</script>
|
同样需要新建文件_sidebar.md，内容如下：
1
2
3
| * [简介](/)
* 数据结构
* [数组](data-structure/array/)
|
个人不建议用这个参数，docsify默认会帮你生成侧边栏，并且有目录效果，可以点击跳转。
全文搜索插件
docsify提供了一些插件，包括全文搜索等，可以通过该地址查询有哪些插件：https://cdn.jsdelivr.net/npm/docsify@4.12.0/lib/plugins/
对于全文搜索插件，需要在index.html里添加search属性以及JavaScript，官方提供的搜索插件好像有点问题，这里用的是其他的搜索插件。如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| <script>
window.$docsify = {
name: 'Java-Note',
repo: 'https://github.com/lewky',
search: {
maxAge: 86400000, // Expiration time, the default one day
paths: 'auto',
placeholder: '🔍 Type to search ',
noData: '😞 No Results! ',
depth: 6
}
}
</script>
<script src="//cdn.bootcss.com/docsify/4.5.9/plugins/search.min.js"></script>
|
目前似乎高于4.5.9版本的搜索插件有bug，只能搜索到首页的数据；建议使用该版本的搜索插件。
此外，使用了无序列表或者有序列表的数据是无法生成对应索引的，也就是说搜索插件无法搜索到列表里的数据。建议尽量别使用列表语法，可以改用特殊符号● 、罗马数字ⅠⅡⅢⅣⅤⅥⅦⅧⅨ 和换行符<br>来代替列表语法。
回到顶部插件
在index.html引入脚本和参数配置：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| <script>
window.$docsify = {
name: 'Java-Note',
repo: 'https://github.com/lewky',
scrollToTop: {
auto: true,
text: 'Top',
right: 15,
bottom: 15,
offset: 300
}
}
</script>
<script src="//unpkg.com/docsify-scroll-to-top/dist/docsify-scroll-to-top.min.js"></script>
|
参数配置有默认值，不配也可以，一共就这几个属性，可以自己随意定制。
代码高亮插件
在index.html引入脚本，可以根据需要引入对应的语言高亮脚本：
1
2
3
4
| <script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-java.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-c.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-sql.min.js"></script>
|
复制代码块插件
在index.html引入脚本和参数配置：
1
2
3
4
5
6
7
8
9
10
11
12
| <script>
window.$docsify = {
// docsify-copy-code (defaults)
copyCode: {
buttonText : 'Copy to clipboard',
errorText : 'Error',
successText: 'Copied'
}
}
</script>
<script src="//unpkg.com/docsify-copy-code@2.1.1/dist/docsify-copy-code.min.js"></script>
|
参数配置有默认值，可以不配置直接引入脚本即可使用。
图片缩放插件
在index.html引入脚本即可：
1
| <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
|
添加fontawesome
可以通过引入fontawesome来使用各种免费的矢量图标来丰富页面内容：
1
| <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@5.13.0/css/all.min.css">
|
用法很简单，就是使用<i>标签来引入，而markdown兼容html代码，如下：
1
| <i class="fas fa-fw fa-home"></i>
|
还有其他的动态图用法等，网上教程很多，这里就不赘述了。
PlantUML插件
在index.html引入脚本即可：
1
| <script src="//unpkg.com/docsify-plantuml/dist/docsify-plantuml.min.js"></script>
|
默认主题是default，也可以配置成classic：
1
2
3
4
5
6
7
| <script>
window.$docsify = {
plantuml: {
skin: 'classic',
}
}
</script>
|
远程部署到Pages服务
GitHub Pages支持从三个地方读取文件：
docs目录main分支（以前是叫master分支）gh-pages分支
master分支一般用于个人站点，gh-pages分支需要另外创建一个新的分支（默认GitHub仓库创建的是master分支），对于文档站点，建议直接使用docs目录来部署，这也是前文为什么建议用docs目录进行初始化的原因。
将文档站点推送到GitHub仓库后，在Settings里选择使用main branch和/docs进行部署即可。
参考链接
警告
本文最后更新于 April 14, 2023，文中内容可能已过时，请谨慎使用。
