之前在建立mall项目的文档网站时，运用过不少东西，比如说Docsify、VuePress、Hexo、语雀等。比照了一下，要论运用简单、上线方便仍是Docsify，几分钟上线一个网站也不是问题，今日咱们就来聊聊Docsify的运用！

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

简介

Docsify是一款开源的文档生成东西，目前在Github上已有21K+Star。Docsify能够快速帮你生成文档网站，不同于VuePrese和Hexo的当地是它不会生成静态的.html文件，一切转化工作都是在运行时。

几分钟上线一个项目文档网站，这款开源神器实在太香了！

装置

运用Docsify仅需装置NodeJs和Docsify的CLI东西即可，十分简单。

装置NodeJs

  • 首要下载NodeJs的装置包，下载地址：nodejs.org/dist/v12.14…

  • 下载完结后一路点击下一步装置即可，假如你想修正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/docsify@4"></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/docsify@4/lib/plugins/search.min.js"></script>
  • 增加成功后，文档网站左上角即可开启查找功用。

几分钟上线一个项目文档网站，这款开源神器实在太香了！

代码高亮

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

几分钟上线一个项目文档网站，这款开源神器实在太香了！

一键仿制代码

  • 假如你想完结一键仿制代码，Docsify也是有插件能够支撑的，直接在index.html中增加如下插件即可；
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code@2/dist/docsify-copy-code.min.js"></script>
  • 增加完结后，在咱们代码的右上角就会呈现仿制代码按钮了。

几分钟上线一个项目文档网站，这款开源神器实在太香了！

更换主题

  • Docsify默认的主题尽管不错，但有没有其他主题能够更换呢，这儿引荐一款令人愉悦的主题docsify-themeable，这儿修正下index.htmlhead中导入的css代码即可；
<head>
<!--  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">-->
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
</head>
  • 本文运用的就是这种主题，此主题拥有侧边栏折叠和隐藏功用，用起来仍是挺不错的。

几分钟上线一个项目文档网站，这款开源神器实在太香了！

更多插件

Docsify的扩展插件仍是挺多的，假如你想寻找更多插件的话，无妨参阅下这个开源项目。

github.com/docsifyjs/a…

布置

  • 运用Nginx来布置Docsify也是十分简单的，咱们先来回忆下之前的项目目录；

几分钟上线一个项目文档网站，这款开源神器实在太香了！

  • 在运用VuePress时，咱们需要把Markdown文件编译成html才干布置，运用Docsify咱们无需编译，只需把docs中的文档都拷贝到Nginx的html目录中即可；

几分钟上线一个项目文档网站，这款开源神器实在太香了！

  • 此刻咱们发动Nginx，访问下Nginx服务途径即可检查文档。

几分钟上线一个项目文档网站，这款开源神器实在太香了！

总结

今日带咱们体验了一把Docsify，运用Docsify来建立文档网站确实简单、方便。比照运用VuePress和Hexo来建立文档，尽管功用没有那么强大，可是Docsify无需编译、无需打包布置、修正响应敏捷、对Markdown文档无污染这些优点仍是值得必定的。别的Docsify除了一些插件装备，其他装备根本能够运用Markdown来完结，感兴趣的小伙伴无妨测验下它！

参阅资料

官方文档：docsify.js.org/#/zh-cn/