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

38次阅读

共计 4526 个字符，预计需要花费 12 分钟才能阅读完成。

之前在搭建 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 的安装包，下载地址：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\

装置完 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/

正文完

java

发表至： java

2022-11-08

0

死磕-java线程系列之线程池深入解析体系结构

关于java:Spring-Boot-微服务性能下降九成使用-Arthas-定位根因

Java中重名类冲突处理机制和Jar包加载顺序

java之旅总览

关于xamarin:MASA-MAUI-Plugin-五Android-指纹识别

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

简介

装置

装置 NodeJs

装置 docsify-cli 工具

应用

初始化我的项目

实时预览

定制侧边栏

定制导航栏

定制封面页

插件

全文搜寻

代码高亮

一键复制代码

更换主题

更多插件

部署

总结

参考资料

Just My Socks（注册教程内含优惠码）

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

简介

装置

装置 NodeJs

装置 docsify-cli 工具

应用

初始化我的项目

实时预览

定制侧边栏

定制导航栏

定制封面页

插件

全文搜寻

代码高亮

一键复制代码

更换主题

更多插件

部署

总结

参考资料

Just My Socks（注册教程 内含优惠码）

Just My Socks（注册教程内含优惠码）