几分钟上线一个项目文档网站,这款开源神器实在太香了~
之前在搭建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.14.0/node-v12.14.0-x64.msi
下载完成后一路点击下一步安装即可,如果你想修改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.html
head中导入的css代码即可;
<head>
<!-- <link rel="stylesheet" href="//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的扩展插件还是挺多的,如果你想寻找更多插件的话,不妨参考下这个开源项目。
https://github.com/docsifyjs/awesome-docsify
部署
- 使用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/
几分钟上线一个项目文档网站,这款开源神器实在太香了~相关推荐
- 几分钟上线一个项目文档网站,这款开源神器实在太香了!
之前在搭建mall项目的文档网站时,使用过不少工具,比如说Docsify.VuePress.Hexo.语雀等.对比了一下,要论使用简单.上线快捷还是Docsify,几分钟上线一个网站也不是问题,今天我 ...
- 秒建炫酷的开源项目文档,这款神器用起来够优雅
学习过我的开源项目mall的朋友应该知道,我有一个使用Docsify 搭建的项目文档网站.使用Docsify搭建文档网站虽然简单,但是缺少分类.标签.SEO这类功能,随着文档越来越多,查找起来有点不方 ...
- dsoframer-在线编辑office文档,一款开源的由微软提供
office 文档在线编辑的功能,,大多使用OCX中间间,希望找一个开源免费的, 国内: dsoframer.ocx: WebOffice.ocx EhaiOfficeOnWeb.ocx office ...
- GitHub标星75k,阿里15W字的Spring高级文档(全彩版),真的太香了
随着 Spring 使用越来越广泛,Spring 已经成为 Java 程序员面试的必问知识点,很多同学对于Spring理解不是那么的深刻,经常就会被几个连环追问给干趴了! 今天小编整理了一下一线架构师 ...
- 如何用github制作html网站,如何使用docsify和GitHub页面创建文档网站?
如何自己创建网站?文档是帮助用户使用开源项目的一个重要部分,但它并不总是开发人员的首要任务,因为他们可能更关心如何使他们的应用程序更好地使用它.这就是为什么开发人员可以更容易地发布文档.在本教程中,我 ...
- 转载文章-【工具】10分钟快速搭建属于自己的文档网站-来自掘金
掘金 首页 探索掘金 搜索 lvhanghmm的头像 Gopal lv-4 2021年03月09日 阅读 9930 关注 [工具]10分钟快速搭建属于自己的文档网站 前言 很多同学都希望能够拥有自己的 ...
- 如何写一个好的Github项目文档
一.什么是Github? Github是通过Git进行版本控制的软件源代码托管服务平台. Github除了Git代码仓库托管及基本的Web管理界面以外,它还提供了一些方便社会化共同软件开发的功能,即一 ...
- 推荐一个免费文档搜索下载网站http://freedownloadbooks.net/
推荐一个免费文档搜索下载网站http://freedownloadbooks.net/
- Github+docsify打造在线文档网站
写在前面 搭建这个在线文档的目的是方便自己对学习笔记的查看,比较喜欢 docsify 的主题风格,所以没有用 Github Pages 直接给的主题,自己根据官方文档进行了配置,目前已经成功上线. 1 ...
最新文章
- 人脸识别中的人脸监测、定位校准和对比等技术
- golang 简单tls协议 使用实例
- linux ubuntu16.04 编译opencv教程(没编过,有时间再弄,推流不用opencv也行的)
- JavaScript 书写方式与注释
- 插图 引用 同一行两个插图_数学身份的优雅LED插图
- android设置高德的3d,高德地图3D版的使用方法
- 操作系统课程设计 Kernel编译和WinDbg启动 批处理文件
- php如何生成伪静态url,Thinkphp里关于U函数生成URL伪静态
- 11年的macbook还能用吗_8年老本的第二春:2011款Macbook Pro换血记
- ps画画模糊笔刷_Photoshop绘图工具之模糊/锐化/涂抹工具
- vsc编辑器设置背景图
- C#如何获取本机网络ip地址
- RHCE 第八次作业
- 汉语中的 熟语中的成语900个
- 获取物料批次特性取值BAPI_SAP刘梦_新浪博客
- CSS3 图片扫光/辉光
- 一元域名真假?一元域名注册有哪些风险?
- 简要损益科目口诀,营业外收支和其他业务收支的区别
- JAVA里的jsp网页背景_【JavaWeb】JSP 页面
- 搜索-Query Understanding (QU)