使用docsify构建专业文档网站(下)

tags: docsify doc github

1.引言

上一篇文章对使用docsify进行文档网站构建进行了介绍，并且可以在本地进行访问。但对于开发者而言，一般都希望自己的文档，blog或者书籍可以发布到网上，进行知识分享，同时可以评论互动。特别是对软件进行开源的，一般都配套有对应的说明文档、帮助文档、开发文档等等。而github作为开发者的聚集地，最适合文档发布了。本文将对使用docsify写好的文档发布到github上进行详细描述。

2.使用Github Pages部署文档

github有GitHub Pages功能，相当于一个静态网站的显示功能，GitHub Pages 支持从三个地方读取文件:

• 1、master分支
• 2、master分支下的docs目录
• 3、gh-pages分支

1、如果你的文档直接是在项目根目录写的，那么可直接把代码推送到master分支上， GitHub Pages里选择master branch. 2.如果你的文档是在master分支下的docs/目录下编写的，那么可直接把代码推送到master分支上，GitHub Pages里选择master branch/docs folder.

一般来说，对于开发者对软件进行开源，一般都会有一个docs目录，作为对此软件的说明、使用手册、开发文档等等，因此，本示例项目(deploy-tool)是master分支下的docs目录中编写，所以GitHub Pages里选择master branch/docs folder的方式部署。这种方式也官方推荐的方式。

首先在github网站上创建好仓库，然后终端打开项目目录(也可以使用TortoiseGit工具)：

git init
mkdir docs
touch docs/index.html
git add .
git commit -m '项目初始化'
git remote add origin https://github.com/username/deploy-tool.git
git push --set-upstream origin master

代码推送到github上后，打开github的仓库，选择Settings -> GitHub Pages -> master branch -> save，注意，需要有docs目录才能选择此项，如下所示：

选择后，会提示你当前的github pages对应的网站发布地址，本示例为https://mianshenglee.github.io/deploy-tool/，此后，用户则可以在docs下存放docsify对应的文件，通过git，对文件进行添加，提交即可，使用发布地址进行访问。如下所示：

3.使用Gitalk添加评论功能

发布了文档网站后，如果想要跟读者互动，希望读者可以对文章进行评论，与作者进行讨论，docsify使用Gitalk插件，结合github实现此功能。

3.1 gitalk介绍

Gitalk 是一个基于 GitHub Issue 和 Preact 开发的评论插件。

Gitalk 的特性：

1、使用 GitHub 登录 2、支持多语言 [en, zh-CN, zh-TW, es-ES, fr, ru] 3、支持个人或组织 4、无干扰模式（设置 distractionFreeMode 为 true 开启） 5、快捷键提交评论 （cmd|ctrl + enter）

使用Gitalk需要你做一些提前准备： 1、在github上创建一个仓库，Gitalk会把评论放在这个仓库的issues里面。 2、在github上申请一个GitHub OAuth application，来让Gitalk有权限操作github上的仓库。

3.2 引入gitalk插件

修改docs目录下的index.html文件，添加gitalk的css和js，并new一个Gitalk出来，同时设置相应的参数(具体参数说明见后面章节)即可。如下：

<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>
  var gitalk = new Gitalk({
      clientID: 'GitHub Application Client ID',
      clientSecret: 'GitHub Application Client Secret',
      repo: 'GitHub repo',
      owner: 'GitHub repo owner',
      admin: ['GitHub repo owner and collaborators, only these guys can initialize github issues'],
      id: location.pathname,      // Ensure uniqueness and length less than 50
      distractionFreeMode: false  // Facebook-like distraction free mode
    })
</script>

配置好后，页面最终效果(https://gitalk.github.io/)：

3.3 申请OAuth application

3.3.1 关于OAuth application

new Gitalk的参数中有github的仓库信息和GitHub Application信息，所以首先创建这两个。在github上创建一个仓库比较简单这里就不讲解了。本章讲一下如何申请一个GitHub OAuth application

注意：如果你打算在自己网站使用Gitalk，并且这个网站的源码在github的仓库上，那么你也可以直接使用这个仓库，Gitalk只使用仓库的Issues。

GitHub OAuth application允许程序来操作你的github账户，可以对github中仓库读写。 详情介绍：https://developer.github.com/apps/about-apps/#about-oauth-apps

3.3.2 申请流程

1、打开github网站登陆后，点击右上角的用户图标，选择Settings 2、 在Settings页面选择Developer settings选项。 3、在Developer settings选择OAuth Apps,然后会在页面右边有一个New OAuth App按钮，点击这个按钮就进入到新建OAuth application页面 4、也可以直接代开这个链接：https://github.com/settings/applications/new ，进入新建页面

在注册OAuth应用页面有如下几个参数需要填写：

Application name：必填，OAuth的名字 Homepage URL：必填，你应用的网址，哪个网站用了Gitalk组件，就填写这个网址 Application description：选填，该OAuth的说明 Authorization callback URL：必填，授权成功后回调网址，跟Homepage URL参数要保持一致 这些参数在注册成功后是可以修改的

参数填好后，点Register application按钮即可完成注册。注册成功后会自动跳转到这个OAuth应用的页面，或者在Developer settings选择OAuth Apps后就能看见你创建的OAuth应用名字，点击它进入这个OAuth应用的页面：

如上图，在新创建的OAuth应用里面的Client ID和Client Secret就是我们需要的参数。

3.4 gitalk参数说明

在当前示例中，使用Gitalk的JavaScript代码中有一些参数：

var gitalk = new Gitalk({
    clientID: '7...f',// GitHub Application Client ID
    clientSecret: '4...e',// GitHub Application secret ID
    repo: 'deploy-tool', // 仓库名
    owner: 'mianshenglee',// 仓库的创建者
    admin: ['mianshenglee'], // 如果仓库有多个人可以操作，那么在这里以数组形式写出
    id: location.pathname // 用于标记评论是哪个页面的
  })

主要参数（完整的可查看官方文档）如下：

• clientID 类型：字符串，必填，申请的OAuth App的Client ID

• clientSecret 类型：字符串，必填，申请的OAuth App的Client Secret

• repo 类型：字符串，必填，github上的仓库名字，用于存放Gitalk评论

• owner 类型：字符串，必填，github仓库的所有者的名字

• admin 类型：数组(元素是字符串)，必填，github仓库的所有者和合作者 (对这个 repository 有写权限的用户)

• id 类型：字符串，选填，页面的唯一标识。长度必须小于50。此参数用于评论和页面对应的标识，如果想让两个页面用一个评论，可设置两个页面的id一样。默认值：location.href(页面URL)

• title 类型：字符串，选填，GitHub issue 的标题，默认值：document.title(HTML中title标签中的值)

注意：

虽然id和title参数是不是必填的选项，但是这个两个参数很重要建议填上： 1、id参数用于评论记录和页面对应的唯一标记，有的时候发现好几个页面评论是一样的，就是由于配置id参数的时候，这几个页面的id是一样导致。由于id参数默认值是location.href页面URL，而有的时候URL中带着页面标题的链接，导致URL长度超过了50个字符长度，会导致创建评论issues失败(长度超过50个会创建失败)，这点要注意。 2、title用于在github仓库issues的标题，如果你想管理评论可以设置一下这个参数，来区分该评论是来自于那个文章。

3.5 gitalk注意事项

3.5.1 初次使用需登录github初始化

引入gitalk，设置好参数，并提交到github中，第一次使用会提示如下信息：

由于使用的是github oauth application，需要对它进行一次授权，因此，根据提示，点击登录你配置的用户的github，登录授权成功后，再访问文档网站，即可发现评论可以使用了。

3.5.2 多个页面评论一样问题处理

对于文档中的页面，都会出现评论功能，有的时候发现好几个页面评论是一样的，即在A页面评论，在B页面也出现了，这就需要了解参数id和title的作用了。id参数用于评论记录和页面对应的唯一标记，如果id一样，则会出现相同评论。由于id参数默认值是location.href页面URL，而有的时候URL中带着页面标题的链接，导致URL长度超过了50个字符长度，会导致创建评论issues失败(长度超过50个会创建失败)，title用于在github仓库issues的标题。在这个教程中，给出了解决方法，设置id和title，同时添加对跳转的js处理如下：

var gitalk = new Gitalk({
    clientID: '7...f',// GitHub Application Client ID
    clientSecret: '4...e',// GitHub Application secret ID
    repo: 'deploy-tool', // 仓库名
    owner: 'mianshenglee',// 仓库的创建者
    admin: ['mianshenglee'], // 如果仓库有多个人可以操作，那么在这里以数组形式写出
    title: location.hash.match(/#(.*?)([?]|$)/)[1],
    id: location.hash.match(/#(.*?)([?]|$)/)[1],
  })
  
  // 监听URL中hash的变化，如果发现换了一个MD文件，那么刷新页面，解决整个网站使用一个gitalk评论issues的问题。
    window.onhashchange = function(event){
      if(event.newURL.split('?')[0] !== event.oldURL .split('?')[0]) {
        location.reload()
      }
    }

说明：

1、由于docsify的链接URL使用的是hash的方式，导致切换页面的时候不会刷新页面，导致整个网站的Gitalk评论使用的是一个评论，因此做了监听hash事件，来刷新页面，这样就能每次切换页面刷新，然后加载对应的评论。 2、关于Gitalk参数id的值，由于点击二级标题后，二级标题会以参数的形式出现在url上，导致长度有事超过了50，所以过滤掉URL中的参数，此外还能解决评论定位不到问题(二级标题会在URL上)。

4.开源项目README.md引用

对于开源项目，一般初始化后都会有README.md文件，作为对开源项目的介绍说明，若想在此文件中添加对文档的跳转，由于在上述的评论处理中，使用hash的方式，因此跳转地址需要把#/添加上，否则在location.hash.match(/#(.*?)([?]|$)/)[1]中会报错。

在本示例中，即把引用地址https://mianshenglee.github.io/deploy-tool/改为https://mianshenglee.github.io/deploy-tool/#/。

5.总结

本篇文章使用docsify结合github pages进行发布部署，同时为了互动，添加了Gitalk插件实现评论功能，并把使用过程中需要注意的问题进行了讲解，希望对有需要使用docsify构建文档网站的同学有帮助。

6.参考资料

• docsify官网： https://docsify.js.org
• docsify教程： https://segmentfault.com/a/1190000017576714
• gitalk官网：https://gitalk.github.io/
• gitalk中文文档：https://github.com/gitalk/gitalk/blob/master/readme-cn.md
• gitalk使用教程：https://segmentfault.com/a/1190000018072952#articleHeader6