docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件，所有转换工作都是在运行时进行。通过docsify我们可以构建一个完整的在线文档网站，并能快捷的部署到Github pages中。

title=

使用docsify前需要先安装node.js，安装方法百度中太多了，自己搜索下就行。

环境

我这里使用的是 ubuntu 14.04 系统，自带的 nodejs 和 npm 低版本进行安装带来的坑超多，需要手动安装新版本。

执行命令，先卸载 ubuntu 自带的 nodejs 和 npm :

sudo apt-get remove nodejs && sudo apt-get remove npm

清理依赖包：

sudo apt-get autoremove

安装 Node.js：

# 下载包文件
cd /opt && wget https://nodejs.org/dist/v8.9.4/node-v8.9.4-linux-x64.tar.xz 
# 解压包文件
xz -d node-v8.9.4-linux-x64.tar.xz && tar vxf node-v8.9.4-linux-x64.tar

为了能在全局使用，我们需要配置环境变量：

nano /etc/profile
#文件最后加上
export PATH=$PATH:/opt/node-v8.9.4-linux-x64/bin

同步文件使环境变量生效：

source /etc/profile

测试一下：

node -v && npm -v

得到正确的版本号，表示安装成功。

安装

node.js 安装完成后，运行npm命令安装docsify命令行

npm i docsify-cli -g

创建项目

创建一个文档项目

docsify init ./docs

创建完成后会生成一个docs文件夹，里面包含有index.html、README.md、.nojekyll三个文件。咱们只需要不断的创建.md文件，并以markdown语法编写内容，docsify即可根据内容完成文档展示了~

多页文档

如果需要创建多个页面，或者需要多级路由的网站，在 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

这个就比较重要了，要看明白，她决定着我们能否正确的定制侧边栏。

定制侧边栏

为了有侧边栏，那么你可以创建你自己的_sidebar.md：

首先，你需要设置loadSidebar为true。详细信息可在配置段落中找到。

<!-- index.html -->

<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>

创建_sidebar.md：

<!-- docs/_sidebar.md -->

- [Home](/)
- [Guide](/guide)

当然，如果需要更进一步的对文档网站进行配置，则需对index.html文件进行修改，具体修改方法可查看官方文档，文档地址：https://docsify.js.org/#/zh-cn/

配置index.html，这里我参考官方文档修改的一个配置:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Document</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app">Please wait...</div>
  <script>
    window.$docsify = {
      //定义路由别名，可以更自由的定义路由规则。 支持正则。
      alias: {
            '/.*/_sidebar.md': '/_sidebar.md'
      },
      auto2top: true, //当路线改变时，滚动到屏幕的顶部。
      coverpage: true, //激活封面功能。如果为true，则会从中加载_coverpage.md。
      executeScript: true, //执行页面上的脚本。只解析第一个脚本标记（演示）。如果存在Vue，则默认开启。
      loadSidebar: true, //_sidebar.md如果为真，则从_sidebar.md文件加载边栏，否则从指定的路径加载。
      loadNavbar: true,//_navbar.md如果为真，则从_navbar.md文件加载navbar ，否则从指定的路径加载。
      mergeNavbar: true,//Navbar将在小屏幕上与侧边栏合并。
      maxLevel: 4,//最大的内容表级别。
      subMaxLevel: 2,//在自定义边栏中添加目录（TOC）。
      name: '',  //文档标题，会显示在侧边栏顶部。
      repo: '',  //配置仓库地址或者 username/repo 的字符串，会在页面右上角渲染一个 GitHub Corner 挂件。
      ga: 'UA-106147152-1',
       //搜索配置项
      search: {
        maxAge: 86400000, // 过期时间，单位毫秒，默认一天
        paths: 'auto', // or 'auto'
        placeholder: '搜索',
        noData: '找不到结果',
        // 搜索标题的最大程级, 1 - 6
        depth: 4
      }
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  <script src="//unpkg.com/docsify/lib/docsify.js" data-load-sidebar></script>
  <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
  <script src="//unpkg.com/docsify/lib/plugins/ga.min.js"></script>
  <script src="//unpkg.com/docsify/lib/plugins/zoom-image.js"></script>
  <script src="//unpkg.com/docsify/lib/plugins/emoji.js"></script>
</body>
</html>

运行

运行一个本地服务器通过 docsify serve 可以方便的预览效果，而且提供 LiveReload 功能，可以让实时的预览。默认访问 http://localhost:3000 。

#默认使用3000端口
docsify serve docs
#自定义端口运行，例如8989端口
docsify serve docs -p 8989

总结

docsify用法和gitbook 差不多，但是样式比较好看，个人理解docsify就是彩色版的gitbook 。

相关推荐

  1. 使用 SystemBack 为 Debian / Ubuntu 创建系统备份
  2. Debian 9/Ubuntu 16.04 如何配置使用NFS服务
  3. 关于Debian/Ubuntu 系统备份及还原的手动方法
  4. 一款基于Node.js的P站(Pixiv)图片批量下载器
  5. Debian/Ubuntu添加/禁止开机启动项
  6. MikuTools：一款网页在线工具箱（视频/音乐解析下载/磁力搜索等）
文章作者：喵斯基部落
原文地址：https://www.moewah.com/archives/122.html
版权声明：本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。非商业转载及引用请注明出处（作者、原文链接），商业转载请联系作者获得授权。