docsify，文档生成利器！

Swimly
15,415 阅读4分钟

前沿

相信很多人都有这种经历，一个项目写好了，尤其是一个组件库，你没有一个文档说明，谁能看得懂？所以一个好的项目，必须要有个通俗易懂的文档说明。当然，这些年markdown如火如荼，github的page也可以让你快速生成一个简单的文档说明，但毕竟写来写去还是在一个readme.md上面做文章，如果一个项目或是组件够大，总不能所有的都写在一个文件里面吧！就算你写的再认真，说实话，也没人愿意去看。

起因

做过前端的小伙伴，element ui想必不陌生，组件库那是相当不错，并且对用户来说很容易入门。为什么？因为他有一个完善的，浅显易懂的文档。

起步

一个偶然的机会了解到docsify，经过一天的摸索觉得有必要写一点什么，以防自己今后查阅什么的。

安装docsify
npm i docsify-cli -g
初始化

初始化必须进到项目根目录，当然如果你像我一样只为了写一个文档而写文档，新建一个空文件夹就行。但是，在这里我要稍微弄的复杂一点，因为我们写好的文档总不是写给自己看，还是要放到github上面供更多人查阅的。所以我们就从新建一个空的github库开始。当然，这过程就不累述了，大家自行创建。创建好之后将repo clone到本地。

然后在当前目录运行如下指令：

docsify init ./docs

会在当前目录新生成一个docs目录。

里面包含这三个文件，先不管都有什么用，我只能告诉你你改的最多的可能就是index.html以及无限量的添加新的markdown文件了。先不管那么多，先跑起来看到页面再说。

docsify serve docs

再次打开浏览器：http://localhost:3000就能看到一个初始化的页面。

当然你可能觉得这一长串指令记不住，那咱们就来个简单的。

打开package.json，在script里面添加一条，如果没有请自行添加：npm init -y

"doc": 'docsify serve docs'

以后直接 npm run doc即可。到了这里一个简单的文档模型就出来了，接下来就着重了解一下他的相关配置：

配置

太简单的配置就不累述了，给个地址，大家点进去自己看docsify,接下来重点说一下如下几个配置项。

loadSidebar

加载自定义导航栏，设置为true即可，它会自动加载指定路径下的_navbar.md，但是我们总想什么东西都要受自己控制，这里我就简称为码控吧！很简单，我们在./docs目录下新建_navbar.md，这样，就可以在这个文件里面自定义我们的侧边栏了。

window.$docsify = {
  // 加载 _navbar.md
  loadSidebar: true,

  // 加载 nav.md
  loadSidebar: 'summary.md'
};

新建setup.md，如上图所示：
我们可以看到上面所示的样子，基本上这就是一个文档的最基础的样子。但是功能远远没有达到我们想要的效果，下面就一起弄几个插件玩玩！

插件

copy to clipboard

将下面的js加在index.html最下面即可。

<script src="//unpkg.com/docsify-copy-code"></script>

然后在README.md中随便写一点代码

其他还有一些插件配置比较简单，接下来介绍下稍微有些繁琐的一个。

Gittalk

看名字估计有些小伙伴就知道是干嘛的，就是一个基于 Github Issue 和 Preact 开发的评论插件。下面一起来了解怎么使用！

<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">

<script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
<script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
<script>
  const gitalk = new Gitalk({
    clientID: 'Github Application Client ID',
    clientSecret: 'Github Application Client Secret',
    repo: 'Github repo',
    owner: 'Github repo owner',
    admin: ['Github repo collaborators, only these guys can initialize github issues'],
    // facebook-like distraction free mode
    distractionFreeMode: false
  })
</script>

配置文件就是上面那些，但是上面还有一些东西要我们自己去填。也就是github application相关的一些配置。 废话不多说，打开 github.com/settings/de…

添加后我们就可以获得相关的配置项： 

<!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">
  <link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: '',
      themeColor: '#19BE6B',
      repo: '',
      loadSidebar: true
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  <script src="//unpkg.com/docsify-copy-code"></script>
  <script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
  <script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
  <script>
    const gitalk = new Gitalk({
      clientID: '9b4355e11242485017da',
      clientSecret: 'fe82f322d0571768a6bf838b515105318397e274',
      repo: 'docsify-starter',
      owner: 'swimly',
      admin: ['swimly'],
      // facebook-like distraction free mode
      distractionFreeMode: true
    })
  </script>
</body>
</html>

最后index.html的配置基本上就上面这样，声明，我这里的clientID,clientSecret是错的，切勿直接复制！

最后来一点图片欣赏一下劳动成果！

到这里一个基本的文档就完成了，接下来就是去完善文档！

部署到github

由于前面我们已经新建了github，直接提交到github的master分支下即可！到这里还没完，同步到github，要怎么让其他人能看到才是关键，接下来进行我们的最后一步，打开最开始我们新建的github项目，切换到setting

找到GitHub pages，将source改成master branch /docs folder。
上面这里就是我们这个文档的地址，直接点开就能看到最终的效果！ 好了，到这里一个完整的流程就结束了，还有更多玩法等待大家共同发掘!

一些链接

doc地址 github

谢谢浏览，欢迎留言，共同讨论！

avatar
文章
阅读
粉丝