docsify，文档生成利器！

时间 2019-11-15 标签 docsify 文档生成利器

前沿

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

原由

作过前端的小伙伴，element ui想必不陌生，组件库那是至关不错，而且对用户来讲很容易入门。为何？由于他有一个完善的，浅显易懂的文档。php

起步

一个偶然的机会了解到docsify，通过一天的摸索以为有必要写一点什么，以防本身从此查阅什么的。css

安装docsify

npm i docsify-cli -g
复制代码

初始化

初始化必须进到项目根目录，固然若是你像我同样只为了写一个文档而写文档，新建一个空文件夹就行。可是，在这里我要稍微弄的复杂一点，由于咱们写好的文档总不是写给本身看，仍是要放到github上面供更多人查阅的。因此咱们就重新建一个空的github库开始。固然，这过程就不累述了，你们自行建立。建立好以后将repo clone到本地。 html

而后在当前目录运行以下指令：

docsify init ./docs
复制代码

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

docsify serve docs
复制代码

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

固然你可能以为这一长串指令记不住，那我们就来个简单的。java

打开package.json，在script里面添加一条，若是没有请自行添加：npm init -yreact

"doc": 'docsify serve docs'
复制代码

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

配置

太简单的配置就不累述了，给个地址，你们点进去本身看docsify,接下来重点说一下以下几个配置项。git

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

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