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 本地实时预览

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选项：

<!-- index.html --><script>window.$docsify = {loadSidebar: true,//设置为 true 后会加载 _sidebar.md 文件loadSidebar: 'summary.md',//添加此项可以设置为自定义加载的文件名subMaxLevel: 2,//生成目录的最大层级，默认值为0，即自定义侧边栏后默认不会再生成目录}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

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

<!-- docs/_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 跳过此回退过程，直接读取文件。

<script>window.$docsify = {loadSidebar: true,alias: {'/.*/_sidebar.md': '/_sidebar.md'}}
</script>

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

2.4 页面标题

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

<!-- docs/_sidebar.md -->
* [Home](/)
* [Guide](guide.md "The greatest guide in the world")

三、定制导航栏

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

<!-- index.html --><body><nav><a href="#/">EN</a><a href="#/zh-cn/">中文</a></nav><div id="app"></div>
</body>

接着需要配置loadNavbar：

<!-- index.html --><script>window.$docsify = {loadNavbar: true,//设置为true后会加载 _navbar.md 文件loadNavbar: 'nav.md',//添加此项可以自定义加载的文件名}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

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

<!-- _navbar.md -->* [En](/)
* [中文](/zh-cn/)

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

<!-- _navbar.md -->* 入门* [快速开始](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中添加封面页的配置：

<script>window.$docsify = {coverpage: true,//设置为true后会加载 _coverpage.md 文件coverpage: 'cover.md',//添加此项可以自定义加载的文件名coverpage: ['/', '/zh-cn/'],//也可同时设置多个页面的封面coverpage: {//也可同时设置多个封面并指定具体文件名'/': 'cover.md','/zh-cn/': 'cover.md',},}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

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

<!-- _coverpage.md -->![logo](_media/icon.svg)# docsify <small>3.5</small>> 一个神奇的文档网站生成器。- 简单、轻便 (压缩后 ~21kB)
- 无需生成 html 文件
- 众多主题[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#docsify)

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

<!-- _coverpage.md --># docsify <small>3.5</small>[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',// orrepo: '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.mdhomepage:'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',// orname: '<span>docsify</span>',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 内建立文档索引。默认过期时间为一天，可以自己指定需要缓存的文件列表或者配置过期时间。

<script>window.$docsify = {search: 'auto', // 默认值search : ['/',            // => /README.md'/guide',       // => /guide.md'/get-started', // => /get-started.md'/zh-cn/',      // => /zh-cn/README.md],// 完整配置参数search: {maxAge: 86400000, // 过期时间，单位毫秒，默认一天paths: [], // or 'auto'placeholder: 'Type to search',// 支持本地化placeholder: {'/zh-cn/': '搜索','/': 'Type to search'},noData: 'No Results!',// 支持本地化noData: {'/zh-cn/': '找不到结果','/': 'No Results'},// 搜索标题的最大层级, 1 - 6depth: 2,hideOtherSidebarContent: false, // 是否隐藏其他侧边栏内容// 避免搜索索引冲突// 同一域下的多个网站之间namespace: 'website-1',// 使用不同的索引作为路径前缀（namespaces）// 注意：仅适用于 paths: 'auto' 模式//// 初始化索引时，我们从侧边栏查找第一个路径// 如果它与列表中的前缀匹配，我们将切换到相应的索引pathNamespaces: ['/zh-cn', '/ru-ru', '/ru-ru/v1'],// 您可以提供一个正则表达式来匹配前缀。在这种情况下，// 匹配到的字符串将被用来识别索引pathNamespaces: /^(\/(zh-cn|ru-ru))?(\/(v1|v2))?/}}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

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

<script src="//polyfill.io/v3/polyfill.min.js?features=String.prototype.normalize"></script>

图片缩放 - Zoom image

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

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>

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

复制到剪切板

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

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>

字数统计

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

<script src="//unpkg.com/docsify-count/dist/countable.js"></script>

同时添加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语法支持时:

<scriptsrc="https://cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-java.min.js"></script>

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

```html
<p>This is a paragraph</p>
<a href="//docsify.js.org/">Docsify</a>
``````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 之类的文档非常合适。喜欢本文可以关注我~有问题可以留言或私信我。