docsify编写类似vue风格文档
前言
作为一名java后端开发人员，习惯编写markdown技术文档。希望写的资料可以通过个人网站保存，便于日后查看，我们有很多工具如：GitBook,Hexo 这类偏向博客风格网站工具。这里我们使用docsify文档工具，结合github pages功能可以发布为在线文档网站，而且提交会自动更新网站。
1 、介绍
docsify一个神奇的文档网站生成工具。
官网使用文档: https://docsify.js.org/#/zh-cn/
以下是vue风格文档预览，
image.png
2、快速开始
2.1 安装docsify-cli工具
cnpm i docsify-cli -g
该工具用于创建及本地预览文档网站。安装成功后
[lxx@lsyPro docsify ]$ sudo cnpm i docsify-cli -g
Password:
Downloading docsify-cli to /usr/local/lib/node_modules/docsify-cli_tmp
Copying /usr/local/lib/node_modules/docsify-cli_tmp/_docsify-cli@4.4.3@docsify-cli to /usr/local/lib/node_modules/docsify-cli
Installing docsify-cli's dependencies to /usr/local/lib/node_modules/docsify-cli/node_modules
// ...... 省略......
[1/1] scripts.postinstall docsify@^4.12.1 finished in 199ms
peerDependencies WARNING livereload@0.9.3 › ws@^7.4.3 requires a peer of bufferutil@^4.0.1 but none was installed
peerDependencies WARNING livereload@0.9.3 › ws@^7.4.3 requires a peer of utf-8-validate@^5.0.2 but none was installed
All packages installed (194 packages installed from npm registry, used 5s(network 5s), speed 698.15kB/s, json 172(368.18kB), tarball 2.97MB)
[docsify-cli@4.4.3] link /usr/local/bin/docsify@ -> /usr/local/lib/node_modules/docsify-cli/bin/docsify
2.2 新建文档编写目录文件夹。
这里建的文件夹：lsy-notes；对应目录/Users/lxxx/Documents/my-documentweb/docsify/lsy-notes。
切换到新建文件目录下，初始化站点信息：docsify init ./docs，实际上这里可以直接docsify init ./, 将当前目录为文档主目录。
[lxx@lsyPro lsy-notes ]$ docsify init ./docs
会在当前目录下生成docs文件夹。其实这个文件夹就是将来我们存放md格式的博客文件的地方。docs文件夹下生成3个文件如下：
[lxxx@lsyPro docs (master)]$ ll -al
total 16
drwxr-xr-x 5 longshiyang staff 160B 8 6 14:34 .
drwxr-xr-x 4 longshiyang staff 128B 8 6 14:34 ..
-rw-r--r-- 1 longshiyang staff 0B 10 26 1985 .nojekyll
-rw-r--r-- 1 longshiyang staff 34B 10 26 1985 README.md
-rw-r--r-- 1 longshiyang staff 604B 8 6 14:34 index.html
- index.html 入口文件
- README.md 会做为主页内容渲染
- .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件
2.3 、本地预览网站
在当前目录下执行：docsify serve ./docs
[lxx@lsyPro spring ]$ docsify serve ./docs
Serving /Users/lxx/Documents/my-documentweb/docsify/lsy-notes/docs now.
Listening at http://localhost:56581
浏览器打开：http://localhost:56581如下图，初始的页面
image.png
3、部署发布到github上
利用github的GitHub Pages功能将站点发布到公网。
-
首先github上新建仓库
image.png
-
将本地新建文档目录增加git管理并上传到新建github仓库上，这里不会操作的请参考：https://www.jianshu.com/p/6710b721cac6
-
仓库设置里面settings-->Pages-->master-->/docs提交即可生成
GithubPages如下图
image.png
-
打开
published站点网址能够查看发布成功
image.png
到此我们能够将本地docsify生成的站点发布到公网上了，接下来就是编写文档和配置阶段。
还可以通过以下服务渠道部署
4、编写文档
文档使用markdown形式，编写存放于docs下，可以分文件夹层级，借助于配置左边导航页完成跳转。
5、docsify相关配置
配置docsify主要在index.html下window.$docsify下添加相关参数，结合新增文件配合完成。
<script>
window.$docsify = {
// 配置左侧文档名称
name: '技术笔记',
// 配置右边git图标
repo: 'https://github.com/Geroge1226/lsy-notes.git',
coverpage: true,
// 配置左侧导航栏
loadSidebar: true,
// 配置头部导航栏
loadNavbar: true,
subMaxLevel: 2,
// 完整配置参数
}
</script>
5.1 封面配置
- 在
index.html中window.$docsify增加coverpage:true -
docs目录下新建封面文件_coverpage.md。内容如下：
# 技术文档
> 个人技术栈知识笔记
* Java相关：jdk、jvm、
* 框架技术：spring、mybatis
* 中间件：es、mq、redis
* 数据库技术：mysql
[GitHub](https://github.com/Geroge1226/lsy-notes.git)
[Get Started](#quick-start)
-
预览效果
image.png
5.2、配置Github Corner
- 在
window.$docsify下配置repo: 'git地址'即可。 -
效果图
image.png
5.3、左侧导航栏
-
window.$docsify下增加：loadSidebar: true - 在docs目录下新增：
_sidebar.md，文件内容
* [java](/)
* [java基础](java/java基础)
* [java高并发](java高并发/)
* [3、java虚拟机](java虚拟机/)
* [4、mybatis](mybatis/)
* [5、spring](spring/)
* [5.1 spring简单介绍](spring/spring简单介绍)
* [6、设计模式](设计模式/)
其中[方括号]内容的层级显示，按照实际需要调整即可，（圆括号）内容是实际的文档结构。默认README.md文件名可以不写。
-
效果图
image.png
5.4、设置导航栏位
-
window.$docsify增加loadNavbar: true。 - 在docs目录下增加导航目录文件
_navbar.md文件。 -
_navbar.md文件内容如下。
* java技术
* 框架
* 数据库
* [快速开始](zh-cn/quickstart.md)
* [多页文档](zh-cn/more-pages.md)
* [定制导航栏](zh-cn/custom-navbar.md)
* [封面](zh-cn/cover.md)
* 消息队列
* 前端技术
* 工具
* [配置项](zh-cn/configuration.md)
* [主题](zh-cn/themes.md)
* [使用插件](zh-cn/plugins.md)
* [Markdown 配置](zh-cn/markdown.md)
* [代码高亮](zh-cn/language-highlight.md)
-
效果图
image.png
6、使用中踩过的坑
最新通过docsify init生产的index.html如下，该@4版本下，在按照官网说明配置很多功能会出现问题：
- 1、导航不显示。
- 2、搜索会有多个输入框。
- 3、文档打开无滚动条。
image.png
参考：https://blog.csdn.net/m0_37965018/article/details/103841362
