MoeWah

使用docsify快速生成在线文档
docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成...
扫描右侧二维码阅读全文
27
2018/09

使用docsify快速生成在线文档

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

docsify

使用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.htmlREADME.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 。

最后修改:2019 年 04 月 06 日 12 : 31 PM
给作者续一杯咖啡

2 条评论

  1. 小可哦

    怎么导出成静态html或者pdf呢?这是一个问题啊。。。
    或者导出为别的什么鬼也行啊

    1. MoeWah
      @小可哦

      ⌇●﹏●⌇不支持导出静态页面,你可以考虑gitbook

发表评论