阅读 2859

docsify,文档生成利器!

前沿

相信很多人都有这种经历,一个项目写好了,尤其是一个组件库,你没有一个文档说明,谁能看得懂?所以一个好的项目,必须要有个通俗易懂的文档说明。当然,这些年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

谢谢浏览,欢迎留言,共同讨论!

关注下面的标签,发现更多相似文章
评论

查看更多 >