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实现文档构建进行讲解，希望能帮助到想构建自己的文档网站的同学。

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.html的app的div中的文字即可，如下：

<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.svg和bg.png需要自己创建并放到_media目录下

设置封面后，效果如下：

3.4 编写`markdown`内容

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

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官网： docsify.js.org
docsify教程： segmentfault.com/a/119000001…
markdown官网：www.markdown.cn/

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