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

tags: docsify doc github

1.引言

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

2.使用 GithubPages 部署文档

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工具):

代码推送到github上后,打开github的仓库,选择 Settings->GitHubPages->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的 cssjs ,并 new 一个 Gitalk 出来,同时设置相应的参数(具体参数说明见后面章节)即可。如下:

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

3.3 申请OAuth application

3.3.1 关于OAuthapplication

newGitalk 的参数中有github的仓库信息和 GitHubApplication 信息,所以首先创建这两个。在github上创建一个仓库比较简单这里就不讲解了。本章讲一下如何申请一个 GitHubOAuthapplication

注意:如果你打算在自己网站使用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应用页面有如下几个参数需要填写:

Applicationname :必填,OAuth的名字 HomepageURL :必填,你应用的网址,哪个网站用了Gitalk组件,就填写这个网址 Applicationdescription :选填,该OAuth的说明 Authorizationcallback URL :必填,授权成功后回调网址,跟Homepage URL参数要保持一致 这些参数在注册成功后是可以修改的

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

如上图,在新创建的OAuth应用里面的 ClientIDClientSecret 就是我们需要的参数。

3.4 gitalk参数说明

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

主要参数(完整的可查看官方文档https://github.com/gitalk/gitalk/blob/master/readme-cn.md)如下:

  • 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页面也出现了,这就需要了解参数 idtitle 的作用了。id参数用于评论记录和页面对应的唯一标记,如果id一样,则会出现相同评论。由于id参数默认值是location.href页面URL,而有的时候URL中带着页面标题的链接,导致URL长度超过了50个字符长度,会导致创建评论issues失败(长度超过50个会创建失败),title用于在github仓库issues的标题。在这个教程中,给出了解决方法,设置 idtitle ,同时添加对跳转的js处理如下:

说明:

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

我来评几句
登录后评论

已发表评论数()

相关站点

+订阅
热门文章