之前在搭建mall我的项目的文档网站时，应用过不少工具，比如说Docsify、VuePress、Hexo、语雀等。比照了一下，要论应用简略、上线快捷还是Docsify，几分钟上线一个网站也不是问题，明天咱们就来聊聊Docsify的应用！

SpringBoot实战电商我的项目mall（50k+star）地址：https://github.com/macrozheng/mall

简介

Docsify是一款开源的文档生成工具，目前在Github上已有21K+Star。Docsify能够疾速帮你生成文档网站，不同于VuePrese和Hexo的中央是它不会生成动态的.html文件，所有转换工作都是在运行时。

装置

应用Docsify仅需装置NodeJs和Docsify的CLI工具即可，非常简单。

装置NodeJs

  • 首先下载NodeJs的安装包，下载地址：https://nodejs.org/dist/v12.1...
  • 下载实现后一路点击下一步装置即可，如果你想批改npm的模块装置门路和缓存门路的话，能够应用如下命令；
# 批改npm的全局装置模块门路npm config set prefix "D:\developer\env\node-v12.14.0\node_global"# 批改npm的缓存门路npm config set cache "D:\developer\env\node-v12.14.0\node_cache"
  • 而后增加零碎环境变量NODE_PATH；
NODE_PATH = D:\developer\env\node-v12.14.0
  • 再在零碎环境变量的Path中增加如下门路即可。
%NODE_PATH%\%NODE_PATH%\node_global\

装置docsify-cli工具

  • 装置完NodeJs后，可应用如下命令装置Docsify的CLI工具。
npm i docsify-cli -g

应用

环境装置实现后，上面咱们来聊聊Docsify的应用。

初始化我的项目

  • 首先咱们须要应用如下命令初始化一个我的项目，留神提醒找不到docsify命令的话，多半是NodeJs的环境变量配置有问题。
docsify init ./docs
  • 我的项目初始化实现后根本构造如下
-| docs/  -| .nojekyll  -| index.html  -| README.md

实时预览

  • 如果你想实时预览我的项目的话，能够应用如下命令；
docsify serve docs
  • 启动还是十分疾速的，上面是我革新实现的文档网站最终效果图，还是不错的，拜访地址：http://localhost:3000

定制侧边栏

  • 从下面的效果图大家能够看到，左侧有个侧边栏用于显示文档目录和纲要，侧边栏能够在index.html文件中进行配置；
<script>  window.$docsify = {    loadSidebar: true,    maxLevel: 2,    subMaxLevel: 4,    alias: {      '/.*/_sidebar.md': '/_sidebar.md'//避免意外回退    }  }</script><script src="//cdn.jsdelivr.net/npm/[email protected]"></script>
  • 而后在docs目录下增加侧边栏的配置文件_sidebar.md，增加如下配置即可；
* 序章    * [mall架构及性能概览](foreword/mall_foreword_01.md)    * [mall学习所需知识点](foreword/mall_foreword_02.md)* 架构篇    * [mall整合SpringBoot+MyBatis搭建根本骨架](architect/mall_arch_01.md)    * [mall整合Swagger-UI实现在线API文档](architect/mall_arch_02.md)
  • 此时咱们就能够看到网站左侧呈现侧边栏了，大家能够发现Docsify不同于VuePress，能够间接应用Markdown进行侧边栏配置。

定制导航栏

  • Docsify还反对顶部导航栏的配置，间接批改index.html文件，增加如下配置；
<script>  window.$docsify = {    loadNavbar: true,    alias: {      '/.*/_navbar.md': '/_navbar.md'//避免意外回退    }  }</script>
  • 而后创立_navbar.md文件，增加如下配置即可；
* 演示  * [后盾治理](http://www.macrozheng.com/admin/index.html)  * [挪动端](http://www.macrozheng.com/app/mainpage.html)* 我的项目地址  * [后盾我的项目](https://github.com/macrozheng/mall)  * [前端我的项目](https://github.com/macrozheng/mall-admin-web)  * [学习教程](https://github.com/macrozheng/mall-learning)  * [我的项目骨架](https://github.com/macrozheng/mall-tiny)* SpringCloud  * [SpringCloud版本](https://github.com/macrozheng/mall-swarm)  * [SpringCloud教程](https://github.com/macrozheng/springcloud-learning)
  • 此时咱们的文档网站顶部就能够显示导航栏了。

定制封面页

  • Docsify还反对封面页的配置，间接批改index.html文件，增加如下配置；
<script>  window.$docsify = {    coverpage: true  }</script>
  • 而后创立_coverpage.md文件，增加如下配置即可；
![logo](images/mall.svg)# mall-learning> mall学习教程，架构、业务、技术要点全方位解析。mall我的项目（50k+star）是一套电商零碎，应用现阶段支流技术实现。  涵盖了SpringBoot、MyBatis、Elasticsearch、RabbitMQ、Redis、MongoDB、Mysql等技术，采纳Docker容器化部署。[GitHub](https://github.com/macrozheng/mall-learning)[Get Started](README.md)
  • 此时封面页将展现如下成果，你在批改配置的时候能够发现，Docsify批改配置和内容后能够立即失效，十分疾速，比起VuePress的编译快多了。

插件

Docsify还有丰盛的插件反对，这里咱们咱们聊聊一些罕用的插件应用。

全文搜寻

  • 如果你想实现全文搜寻性能的话，能够在index.html中增加搜寻插件配置；
<script>  window.$docsify = {    search: {      placeholder: '搜寻',      noData: '找不到后果!',      depth: 3    },  }</script><script src="//cdn.jsdelivr.net/npm/[email protected]/lib/plugins/search.min.js"></script>
  • 增加胜利后，文档网站左上角即可开启搜寻性能。

代码高亮

  • 如果你想实现代码高亮显示的话，能够在index.html中增加代码高亮的插件；
<script src="//cdn.jsdelivr.net/npm/[email protected]/components/prism-java.min.js"></script><script src="//cdn.jsdelivr.net/npm/[email protected]/components/prism-sql.min.js"></script><script src="//cdn.jsdelivr.net/npm/[email protected]/components/prism-bash.min.js"></script><script src="//cdn.jsdelivr.net/npm/[email protected]/components/prism-yaml.min.js"></script><script src="//cdn.jsdelivr.net/npm/[email protected]/components/prism-xml.min.js"></script>
  • 以上是几种常见的代码高亮显示插件，增加实现后就能够实现代码的高亮显示的。

一键复制代码

  • 如果你想实现一键复制代码，Docsify也是有插件能够反对的，间接在index.html中增加如下插件即可；
<script src="//cdn.jsdelivr.net/npm/[email protected]/dist/docsify-copy-code.min.js"></script>
  • 增加实现后，在咱们代码的右上角就会呈现复制代码按钮了。

更换主题

  • Docsify默认的主题尽管不错，但有没有其余主题能够更换呢，这里举荐一款令人愉悦的主题docsify-themeable，这里批改下index.htmlhead中导入的css代码即可；
<head><!--  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/[email protected]/lib/themes/vue.css">-->  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/[email protected]/dist/css/theme-simple.css"></head>
  • 本文应用的就是这种主题，此主题领有侧边栏折叠和暗藏性能，用起来还是挺不错的。

更多插件

Docsify的扩大插件还是挺多的，如果你想寻找更多插件的话，无妨参考下这个开源我的项目。

https://github.com/docsifyjs/...

部署

  • 应用Nginx来部署Docsify也是非常简单的，咱们先来回顾下之前的我的项目目录；

  • 在应用VuePress时，咱们须要把Markdown文件编译成html能力部署，应用Docsify咱们无需编译，只需把docs中的文档都拷贝到Nginx的html目录中即可；

  • 此时咱们启动Nginx，拜访下Nginx服务门路即可查看文档。

总结

明天带大家体验了一把Docsify，应用Docsify来搭建文档网站的确简略、快捷。比照应用VuePress和Hexo来搭建文档，尽管性能没有那么弱小，然而Docsify无需编译、无需打包部署、批改响应迅速、对Markdown文档无污染这些长处还是值得必定的。另外Docsify除了一些插件配置，其余配置根本能够应用Markdown来实现，感兴趣的小伙伴无妨尝试下它！

参考资料

官网文档：https://docsify.js.org/#/zh-cn/