docsify操作和Docker部署流程文档

前言

根据官网介绍：
docsify是一个神奇的文档网站生成器。
docsify 会动态生成您的文档网站。与 GitBook 不同，它不会生成静态 html 文件。相反，它会智能地加载和解析您的Markdown文件，并将其显示为网站。要开始使用它，您需要做的就是创建一个索引 .html 并将其部署在 GitHub Pages 上。

当然我们也可以使用 Docker 非常方便的容器化部署。
内部 API 管理工具我们使用 yapi，但对于公开 API 获取和使用就不是很方便，所以对于有公开 API 文档需求的小伙伴来说，这正是一个非常优秀的查看和检索工具。

这里有一份 docker部署的 docsify 上的本文复刻版本 https://docsify.work.asrtts.cn/#/guide (点击查看)

下面本文会进行 docsify 的初始化、目录结构、部分功能介绍和部署介绍。
想部署快速验证可以直接看第七小节。

正文

本文档旨在帮助操作人员快速使用docsify构建文档，并完成相应的部署和测试。

一、初始化项目 1.1 安装node.js

下载地址：https://nodejs.org/

下载完成后点击安装

查看node版本，命令：

node -v

1.2 安装docsify-cli工具

推荐全局安装 docsify-cli 工具，可以方便地创建及在本地预览生成的文档。

命令行执行：

npm i docsify-cli -g

1.3 初始化文档结构

创建一个本地文件夹docs作为编写文档的位置，执行命令：

docsify init ./docs

初始化成功后，./docs目录下会创建以下几个文件：

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

直接编辑 docs/README.md 就能更新文档内容，也可以通过嵌入文件的方式添加内容。

例如，可以在README.md文件的末尾加上这一行：

[filename](../_media/example.md ':include')

example.md 文件的内容将会直接接续主页的末尾显示。

1.4 本地实时预览

在./docs目录的上级目录中执行命令：

docsify serve docs

即可启动一个本地服务器，可以方便地实时预览效果。默认访问地址为： http://localhost:3000

二、制作多页文档 2.1 多页面文档结构

如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。例如创建一个 guide.md 文件，那么对应的路由就是 /#/guide。

假设目录结构如下：

.
└── docs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        └── guide.md

那么对应的访问页面是：

docs/README.md        => http://domain.com
docs/guide.md         => http://domain.com/guide
docs/zh-cn/README.md  => http://domain.com/zh-cn/
docs/zh-cn/guide.md   => http://domain.com/zh-cn/guide

2.2 定制侧边栏

默认情况下侧边栏会通过 Markdown 文件自动生成。如果要定制侧边栏，需要创建_sidebar.md文件，也可以自定义文件名。

首先需要修改index.html文件，配置loadSidebar选项：

接着创建 _sidebar.md 文件，内容如下：

* [首页](zh-cn/)
* [指南](zh-cn/guide)

此处需要 ./docs 目录下存在 .nojekyll 命名的空文件，用以阻止 GitHub Pages 忽略命名为下划线开头的文件。

2.3 嵌套的侧边栏

如果希望在浏览到一个目录时，只显示这个目录自己的侧边栏，可以通过在每个文件夹中添加一个 _sidebar.md 文件来实现这一点。

_sidebar.md 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 /zh-cn/more-pages 则从 /zh-cn/_sidebar.md 获取文件，如果不存在则从 /_sidebar.md 获取。可以配置 alias 跳过此回退过程，直接读取文件。

也可以在一个子目录中创建一个 README.md 文件来作为此路由的默认页面。

2.4 页面标题

一个页面的 title 标签是由侧边栏中选中条目的名称所生成的，也可以设置为用侧边栏中选定的条目名称作为页面标题。

* [Home](/)
* [Guide](guide.md "The greatest guide in the world")

三、定制导航栏

如果要定制导航栏，首先修改index.html文件，添加导航栏：

接着需要配置loadNavbar：

然后创建需要加载的Markdown文件：

* [En](/)
* [中文](/zh-cn/)

如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式。

* 入门
    * [快速开始](zh-cn/quickstart.md)
    * [多页文档](zh-cn/more-pages.md)
    * [定制导航栏](zh-cn/custom-navbar.md)
    * [封面](zh-cn/cover.md)


* 配置
    * [配置项](zh-cn/configuration.md)
    * [主题](zh-cn/themes.md)
    * [使用插件](zh-cn/plugins.md)
    * [Markdown 配置](zh-cn/markdown.md)
    * [代码高亮](zh-cn/language-highlight.md)

_navbar.md 加载逻辑和 sidebar 文件一致，从每层目录下获取。

四、定制封面页

在index.html中添加封面页的配置：

添加_coverpage.md文件来配置封面页：

![logo](_media/icon.svg)

# docsify 3.5

> 一个神奇的文档网站生成器。

- 简单、轻便 (压缩后 ~21kB)
- 无需生成 html 文件
- 众多主题

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

目前的背景是随机生成的渐变色，也可以自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。

# docsify 3.5

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



![](_media/bg.png)



![color](#f0f0f0)

五、其他定制项 5.1 常规配置项

window.$docsify 里的配置项，除以上内容涉及的部分外，此处还将介绍一些常用的选项。详细内容请查看https://docsify.js.org/ 。

repo

配置仓库地址或者 username/repo 的字符串，会在页面右上角渲染一个 GitHub Corner 挂件。默认值为null。

window.$docsify = {
    repo: 'docsifyjs/docsify',
    // or
    repo: 'https://github.com/docsifyjs/docsify/',
};

maxLevel

默认情况下会抓取文档中所有标题渲染成目录，可配置最大支持渲染的标题层级。默认值为6。

window.$docsify = {
    maxLevel: 4,
};

hideSidebar

这个选项用来完全隐藏侧边栏，侧边栏的任何内容都不会被渲染。默认值为true。

window.$docsify = {
    hideSidebar: true,
};

auto2top

设置切换页面后是否自动跳转到页面顶部。默认值为false。

window.$docsify = {
    auto2top: true,
};

homepage

设置首页文件加载路径。适合不想将 README.md 作为入口文件渲染，或者是文档存放在其他位置的情况使用。默认值为 README.md 。

window.$docsify = {
    homepage: 'home.md',//更改首页文件为/home.md
    homepage:
        'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',//更改为仓库地址
};

basePath

设置文档加载的根路径，可以是二级路径或者是其他域名的路径。

window.$docsify = {
    basePath: '/path/',

    // 直接渲染其他域名的文档
    basePath: 'https://docsify.js.org/',

    // 或者直接渲染其他仓库
    basePath:
        'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/',
};

relativePath

默认值为false。如果该选项设为 true ，那么链接会使用相对路径。

window.$docsify = {
    relativePath: true,//启用相对路径
};

例如目录结构如下时：

.
└── docs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        ├── guide.md
        └── config
            └── example.md

如果启用了相对路径，当前链接是 http://domain.com/zh-cn/README ，对应的链接会解析为：

guide.md              => http://domain.com/zh-cn/guide
config/example.md     => http://domain.com/zh-cn/config/example
../README.md          => http://domain.com/README
/README.md            => http://domain.com/README

logo && name && themeColor

logo是在侧边栏中出现的网站图标，可以使用CSS来更改大小。

name是文档标题，会显示在侧边栏顶部，也可以使用自定义 HTML 代码来方便地定制。

themeColor为主题色。

window.$docsify = {
    logo: '/_media/icon.svg',
    name: 'docsify',
    // or
    name: 'docsify',
    themeColor: '#3F51B5'，
};

nameLink

点击文档标题后跳转的链接地址。默认值：window.location.pathname

window.$docsify = {
    nameLink: '/',

    // 按照路由切换
    nameLink: {
        '/zh-cn/': '/zh-cn/',
        '/': '/',
    },
};

alias

定义路由别名，可以更自由的定义路由规则。 支持正则。

window.$docsify = {
    alias: {
        '/foo/(.*)': '/bar/$1',
        '/zh-cn/changelog': '/changelog',
        '/changelog':
            'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG',
        '/.*/_sidebar.md': '/_sidebar.md',
    },
};

autoHeader

同时设置 loadSidebar 和 autoHeader 为true时，可以根据 _sidebar.md 的内容自动为每个页面增加标题。

window.$docsify = {
    loadSidebar: true,
    autoHeader: true,
};

5.2 常用插件

此处介绍部分常用插件，详细内容请查看https://docsify.js.org/ 。

全文搜索 - Search

全文搜索插件会根据当前页面上的超链接获取文档内容，在 localStorage 内建立文档索引。默认过期时间为一天，可以自己指定需要缓存的文件列表或者配置过期时间。

当执行全文搜索时，该插件会忽略双音符（例如，“cafe” 也会匹配 “café”）。像 IE11 这样的旧版浏览器需要使用以下 String.normalize() polyfill 来忽略双音符：

图片缩放 - Zoom image

在 index.html 文件中引入 zoom-image.min.js 即可：

鼠标放到一张图片上时会出现缩小或者放大的图标，点击后就可以改变图片的形态。

复制到剪切板

在所有的代码块上添加一个简单的Click to copy按钮来允许用户从你的文档中轻易地复制代码。在 index.html 文件中引入 docsify-copy-code 即可：

字数统计

提供统计中文汉字和英文单词的功能，并且排除了一些markdown语法的特殊字符例如*、-等。需要在 index.html 文件中引入 countable.js ：

同时添加count配置项：

window.$docsify = {
    count:{
        countable:true,
        fontsize:'0.9em',
        color:'rgb(90,90,90)',
        language:'chinese'
    }
}  

代码高亮

docsify内置的代码高亮工具是 Prism。Prism 默认支持的语言如下：

Markup - markup, html, xml, svg, mathml, ssml, atom, rss
CSS - css
C-like - clike
JavaScript - javascript, js

添加额外的语法支持需要通过CDN添加相应的语法文件，比如需要添加java语法支持时:

要使用语法高亮，需要在代码块第一行添加对应的语言声明，示例如下:

```html
This is a paragraph
Docsify
```

```java
System.out.println("hello");
```

5.3 Markdown 配置

内置的 Markdown 解析器是 marked，可以修改它的配置。同时可以直接配置 renderer。

window.$docsify = {
    markdown: {
        smartypants: true,
        renderer: {
            link: function() {
                // ...
            }
        }
    }
}

也可以完全定制 Markdown 解析规则:

window.$docsify = {
    markdown: function(marked, renderer) {
        // ...

        return marked
    }
}

六、文档语法扩展

docsify 扩展了一些 Markdown 语法，可以让文档更易读。详细内容查看https://docsify.js.org/ 。

6.1 强调内容

语法为 !> 内容

!> 一段重要的内容，可以和其他 **Markdown** 语法混用。

6.2 普通提示

语法为 ?> 内容

?> _TODO_ 完善示例

6.3 忽略编译连接

当需要在链接上加入相对路径时，需要防止docsify编译。例如：

[link](/demo/)

编译结果为 link ，并且会加载 /demo/README.md 。

[link](/demo/ ':ignore')

编译结果为 link，页面会跳转到 /demo/index.html 。

也可以为链接设置标题：

[link](/demo/ ':ignore title')

编译结果为 link

七、部署文档 7.1 Docker部署（官网修复版）

注：不知道什么原因官网所介绍的 docker 部署实例并不能通过，下面是多次测试验证后的修复版本。

• 创建Dockerfile

FROM node:latest
WORKDIR /docsify
RUN npm install -g docsify-cli@latest --registry https://registry.npm.taobao.org docsify-cli@latest
ENTRYPOINT docsify init ./docs && docsify serve ./docs

构建 docker 镜像：

docker build -f Dockerfile -t docsify:1.0 .

运行 docker 镜像：

docker run -idt -p 3000:3000 -v /home/docsify:/docsify docsify:1.0
# -p 冒号前面的 3000 可以改成宿主机需要暴露的端口号 
# -v 冒号前面的 /home/docsify 可以改成宿主机文件存放地址

这时候去请求 domain:3000 就可以访问到页面了。

然后在宿主机下 /home/docsify/docs 即可看到 md 文件，修改文件后页面会即使生效，赞！

这里 /home/docsify 完全可以用 git 建个仓库管理下，当然用其他传文件方法也可以。

7.2 ZEIT Now部署

安装Now CLI：

npm i -g now

切换到 docsify 网站的文档目录：

cd docs

部署：

now

7.3 部署到GitHub Pages

提交代码到GitHub，将文档放在 docs/ 目录下，在设置页面开启 GitHub Pages 功能并选择 master branch /docs folder 选项。

7.4 部署到Gitee Pages

在对应的 Gitee 仓库服务中选择 Gitee Pages，选择要部署的分支，填写要部署的分支上的目录，例如docs，填写完成之后点击启动即可。

总结

如果有自己的服务器和域名，非常推荐使用 Docker 容器化部署方式，当然个人使用也可以直接使用 GitHub Pages 或 Gitee Pages，快速编写公开 API 之类的文档非常合适。喜欢本文可以关注我~有问题可以留言或私信我。