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 。内容如下：

![logo](https://docsify.js.org/_media/icon.svg)
# 技术文档
> 个人技术栈知识笔记
* 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、文档打开无滚动条。