数据共享-spring batch(9)上下文处理 还在手工生成数据库文档?3个步骤自动完成了解一下 python处理Excel文件 python基本操作-文件、目录及路径 MinIO 的分布式部署 利用 MinIO 轻松搭建静态资源服务 搞定SpringBoot多数据源(3):参数化变更源 搞定SpringBoot多数据源(2):动态数据源 搞定SpringBoot多数据源(1):多套源策略 java开发必学知识:动态代理 springboot+apache前后端分离部署https springboot+logback日志输出企业实践(下) springboot+logback日志输出企业实践(上) springboot+swagger接口文档企业实践(下) springboot+swagger接口文档企业实践(上) 查阅了十几篇学习资源后,我总结了这份AI学习路径 java应用监测(8)-阿里诊断工具arthas java应用监测(7)-在线动态诊断神器BTrace java应用监测(6)-第三方内存分析工具MAT java应用监测(5)-可视化监测工具 java应用监测(4)-线上问题排查套路 java应用监测(3)-这些命令行工具你掌握了吗 java应用监测(2)-java命令的秘密 java应用监测(1)-java程序员应该知道的应用监测技术 mongo同步-spring batch(8)的mongo读写组件使用 使用docsify构建专业文档网站(下) 使用docsify构建专业文档网站(上) 调度与监控-spring batch(7)结合xxl-job进行批处理 增量同步-spring batch(6)动态参数绑定与增量同步 便捷的数据读写-spring batch(5)结合beetlSql进行数据读写 决战数据库-spring batch(4)数据库到数据库 快速使用组件-spring batch(3)读文件数据到数据库 快速了解组件-spring batch(2)之helloworld 数据批处理神器-Spring Batch(1)简介及使用场景 部署工具(deploy-tool)开源 java服务安装(三):使用appassembler java服务安装(二):使用commons-daemon java服务安装(一):使用java service wrapper及maven打zip包

使用docsify构建专业文档网站(上)

2019年07月12日

使用docsify构建专业文档网站(上)

tags: docsify doc github


1.引言

在软件开发过程中,编程人员经常需要写文档,如开发文档、接口文档、使用手册等,也会经常编写blog记录开发过程,技术感悟。对于这些文档,一般情况下编写人员有以下几种需求:编写简单、对外发布、格式友好、形式专业。而编写的工具则有好多,包括以下几类:

  • word工具类:如office word,wps,txt等
  • 平台博客类:csdn,简书,oschina等
  • 自建网站类:github,hexo,gitbook,markdown等
  • 知识工具类:confluence,语雀,看云等

当然,各种工具有各自的优缺点,简单一点的话,使用语雀、看云来写长系列文章或者书籍也比较适合,但作为一个开发人员,希望找一个能属于自己的,简单的,有点逼格的文档工具,特别是针对开源软件文档编写,放个pdf或者doc文档,不便于维护,格调也不够高,最好能跟github关联,即时可看,又方便维护,如此,则非docsify莫属了(当然gitboot也行)。如下可以截图看一下基于docsify构建的文档。本文针对如何使用docsify实现文档构建进行讲解,希望能帮助到想构建自己的文档网站的同学。

docsify官网

另一种样式

2.docsify简介

docsify官网的介绍,一句话:一个神奇的文档网站生成工具,使用它,可以使用简单的方式,构建一个专业的文档网站。如果使用过GitBook和Hexo的同学,可以知识它们使用markdown编写文档,然后转为html进行显示。而docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件,所有转换工作都是在运行时进行。只需要创建一个 index.html ,就可以开始写文档而且直接部署在 GitHub Pages进行发布,方便、快捷、格式友好,样式不错。

3. 使用docsify构建文档

本章节将对如何使用docsify构建文档进行详细描述。

3.1 构建docsify目录结构

3.1.1 目录结构

docsify有其规范的目录结构,创建一个目录,如test,目录下最基本的结构如下:

  • index.html : 入口文件
  • README.md : 会做为主页内容渲染
  • .nojekyll : 用于阻止 GitHub Pages 会忽略掉下划线开头的文件

若在本地测试,.nojekyll可不需要,若发布到Github Pages,则需要此文件。

3.1.2 编写index.html

index.html

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>

注意 此处使用在线引入docsify的js,如//unpkg.com/docsify/lib/docsify.min.js,用户也可以直接下载此文件到本地,进行本地引用。

3.1.3 编写README.MD

文档内容均以markdown的方式编写,README.MD作为文档的首页,如下是README.MD的内容

## 我是首页

这是我的首页介绍

3.1.4 修改logding提示

初始化时会显示 Loading... 内容,可以自定义提示信息。修改index.htmlappdiv中的文字即可,如下:

<div id="app">加载中...</div>

3.1.5 本地预览网站

最方便的就是本地安装一个python(不会安装的请百度),然后使用Python来启动一个服务,对于python3,在此目录下运行以下命令即可启动:

python -m http.server 3000

3000是开启的端口号,用户可自行定义,启动后,出现以下提示: Serving HTTP on 0.0.0.0 port 3000 (http://0.0.0.0:3000/) ...则表示启动成功。使用浏览器访问localhost:3000即可访问文档。如下:

本地运行

至此,已经完成最基本的文档网站了,若是把完整的文档写在README.MD中,文档也基本完成了,可以正常显示。修改文档和index.html后,刷新页面即可显示更新。

3.1.6 使用docsify-cli创建

若已安装nodejs,则可以不手动创建上面的文件,使用npm安装docsify-cli,创建目录,然后使用docsify init ./,它完成的工作与前面手动生成的文件是一致的。具体可参考官方文档

3.2 设置文档侧边栏

如前面示例,默认情况下,文档侧边栏会根据当前文档的标题生成目录,且会把目录全部展开。如下所示: 默认侧边栏

但一般我们写文档或书籍,都习惯把长文档分章节编写(即每章节一个文件),然后显示时目录可折叠,更方便阅读。docsify则提供了多文档侧边栏的定制。

3.2.1 设置多文档侧边栏

假设文档结构(书结构)如下:

版权信息
序
第一篇
  -- 第1章
    -- 1.1 xxx
    -- 1.2 xxx
  -- 第2章
第二篇
  ...

对应的文件如下(注意:由于docsify是根据路径作为url访问的,目录名及文件名不要使用中文或空格):

.
├── a
│   ├── 1.md
│   └── 2.md
├── b
├── copyright.md
├── index.html
├── preface.md
└── README.md

只需要两步即可完成侧边栏设置:

  • (1) 在index.html文件中的window.$docsify添加loadSidebar: true,选项:
<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>
<script src="//unpkg.com/docsify"></script>
  • (2) 根目录创建_sidebar.md文件

编写目录内容,有链接内容则使用[xx](yy)格式,xx是显示内容,yy是连接地址,连接地址以index.html所在目录为当前目录,连接到对应文件的路径,文件后缀md省略。有层次结构的使用空格分隔层次。如下:

* [版权信息](copyright)
* [序](preface)
* 第一篇
  * [第1章](a/1)
  * [第2章](a/2)
* 第二篇
  * [第3章](b/3)

设置完成后,刷新页面,显示结果如下: 设置侧边栏

3.2.2 设置章节目录显示

上述定制的侧边栏仅根据_sidebar.md文件显示了页面大框架的链接,但各章节所在的目录(标题)没有显示,需要在index.html文件中的window.$docsify添加subMaxLevel字段来设置:

<script>
  window.$docsify = {
    loadSidebar: true,
    subMaxLevel: 3
  }
</script>
<script src="//unpkg.com/docsify"></script>

设置后,效果如下:

设置页面目录显示

注意:subMaxLevel类型是number(数字),表示显示的目录层级 如果md文件中的第一个标题是一级标题,那么不会显示在侧边栏,如上图所示

3.2.3 忽略页面标题在侧边栏目录显示

注意: 如果md文件的第一个标题是一级标题,那么默认已经忽略了。

当设置了 subMaxLevel 时,默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题,可以给它添加 {docsify-ignore}

# Getting Started

## Header {docsify-ignore}

该标题不会出现在侧边栏的目录中。

要忽略特定页面上的所有标题,你可以在页面的第一个标题上使用 {docsify-ignore-all} :

# Getting Started {docsify-ignore-all}

## Header

该页面所有标题都不会出现在侧边栏的目录中。

3.3 设置封面

docsify默认是没有封面的,默认有个首页./README.md。通过设置coverpage参数,可以开启渲染封面的功能。

首先需要在index.html文件中的window.$docsify添加coverpage: true选项:

<script>
  window.$docsify = {
    coverpage: true
  }
</script>
<script src="//unpkg.com/docsify"></script>

接着在项目根目录创建_coverpage.md文件,内容格式如下:

![logo](_media/icon.svg)
# 我的文档网站
## 个人文档网站
> 一个神奇的文档网站生成巩固

* Simple and lightweight (~12kb gzipped)
* Multiple themes
* Not build static html files

[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#quick-start)
[Get Started](#quick-start)

目前的背景是随机生成的渐变色,每次刷新都会显示不同的颜色。docsify封面支持自定义背景色或者背景图,在_coverpage.md文档末尾添加:

<!-- 背景图片 -->
![](_media/bg.png)

<!-- 背景色 -->
![color](#fbb30b)

注意: 1.自定义背景配置一定要在_coverpage.md文档末尾。 2.背景图片和背景色只能有一个生效. 3.背景色一定要是#fbb30b这种格式的。 4.icon.svgbg.png需要自己创建并放到_media目录下

设置封面后,效果如下: 封面

3.4 编写markdown内容

如上述示例,文本内容都是使用markdown进行编写,关于markdown的编写规范,可参考官方文档。markdown的编写工具有很多,熟练的可以直接使用文本进行编辑,中文的markdown工具有TyporacmdMarkdown有道云笔记等等。

3.5 选择主题样式

docsify默认提供了不同的主题样式,默认是vue.css。用户可以根据自己需要来使用即可。

<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/dark.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/pure.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/dolphin.css">

还有一些第三方的主题样式,如:

#示例地址:
https://jhildenbiddle.github.io/docsify-themeable/#/customization
#引入方法:
link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">

3.6 添加搜索功能

一般文章提供搜索功能是比较人性化的功能,在docsify中添加搜索功能,只需要在index.html添加search插件,然后在window.$docsify添加search参数即可。如下:

window.$docsify = {
        search: {
            maxAge: 86400000, // 过期时间,单位毫秒,默认一天
            noData: '找不到结果',//搜索不到结果时显示
            paths: 'auto',//自动
            placeholder: '搜索',//搜索框提示
        },
    }
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>

具体参数设置可参考官网

添加搜索功能后,效果如下:

搜索功能

4. 总结

本篇文章介绍了docsify的优点,并对使用docsify构建文档网站的步骤进行说明,分别是:引入docsify文件 -> 设置目录框架 -> 编写markdown内容 -> 设置封面/样式 -> 添加搜索功能。然后使用python启动(当然也可以使用其它web服务器如nginx,apache)提供静态网站服务即可。希望对有需要的同学有所帮助。

5.参考资料

  • docsify官网: https://docsify.js.org
  • docsify教程: https://segmentfault.com/a/1190000017576714
  • markdown官网:http://www.markdown.cn/