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

时间 2019-11-17

原文原文链接

tags: docsify doc githubjavascript

1.引言

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

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

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

2.docsify简介

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

3. 使用docsify构建文档

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

3.1 构建docsify目录结构

3.1.1 目录结构

docsify有其规范的目录结构，建立一个目录，如test，目录下最基本的结构以下：node

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

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

3.1.2 编写`index.html`

index.htmlnginx

<!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，用户也能够直接下载此文件到本地，进行本地引用。git

3.1.3 编写`README.MD`

文档内容均以markdown的方式编写，README.MD做为文档的首页，以下是README.MD的内容github

## 我是首页

这是个人首页介绍
复制代码

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/