乐趣区

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

jiezi

之前在搭建 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/

退出移动版