tags: docsify doc github

文章目录

1.引言
2.使用`Github Pages`部署文档
3.使用`Gitalk`添加评论功能
- 3.1 gitalk介绍
- 3.2 引入gitalk插件
- 3.3 申请OAuth application
- - 3.3.1 `关于OAuth application`
  - 3.3.2 申请流程
- 3.4 gitalk参数说明
- 3.5 gitalk注意事项
- - 3.5.1 初次使用需登录github初始化
  - 3.5.2 多个页面评论一样问题处理
4.开源项目`README.md`引用
5.总结
6.参考资料

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 50distractionFreeMode: 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 IDclientSecret: '4...e',// GitHub Application secret IDrepo: '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 IDclientSecret: '4...e',// GitHub Application secret IDrepo: '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

使用docsify构建专业文档网站(下)相关推荐

使用docsify构建专业文档网站(上)
tags: docsify doc github 文章目录 1.引言 2.docsify简介 3. 使用docsify构建文档 3.1 构建docsify目录结构 3.1.1 目录结构 3.1.2 编 ...
docsify神奇的文档网站生成工具
原文链接个人博客-欢迎访问 docsify 是一个动态生成文档网站的工具.不同于 GitBook.Hexo 的地方是它不会生成将 .md 转成 .html 文件,所有转换工作都是在运行时进行. 这将 ...
Github+docsify打造在线文档网站
写在前面搭建这个在线文档的目的是方便自己对学习笔记的查看,比较喜欢 docsify 的主题风格,所以没有用 Github Pages 直接给的主题,自己根据官方文档进行了配置,目前已经成功上线. 1 ...
Docsify 创建文档网站
文章目录 Docsify 创建文档网站 1 引言 2 Docsify 简介 3 使用 docsify 构建文档 3.1 构建 docsify 目录结构 3.2 添加文档标题名 3.3 添加 GitHu ...
几分钟上线一个项目文档网站，这款开源神器实在太香了！
之前在搭建mall项目的文档网站时,使用过不少工具,比如说Docsify.VuePress.Hexo.语雀等.对比了一下,要论使用简单.上线快捷还是Docsify,几分钟上线一个网站也不是问题,今天我 ...
几分钟上线一个项目文档网站，这款开源神器实在太香了~
之前在搭建mall项目的文档网站时,使用过不少工具,比如说Docsify.VuePress.Hexo.语雀等.对比了一下,要论使用简单.上线快捷还是Docsify,几分钟上线一个网站也不是问题,今天我 ...
docsify 构建文档网站之定制功能（全网最全）
作者: wugenqiang 学习笔记:https://notebook.js.org/ 微信公众号:码客 E 分享(ID:enjoytoshare) 文档后续更新地址:docsify 构建文档网站 ...
如何用github制作html网站,如何使用docsify和GitHub页面创建文档网站？
如何自己创建网站?文档是帮助用户使用开源项目的一个重要部分,但它并不总是开发人员的首要任务,因为他们可能更关心如何使他们的应用程序更好地使用它.这就是为什么开发人员可以更容易地发布文档.在本教程中,我 ...
js预览本地word文档_Github+docsify打造在线文档
效果图如下预览链接:https://a870439570.github.io/interview-docs 快速开始首先先安装好npm和nodejs,这里就不做过多介绍了自信安装即可 (http ...

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

文章目录

1.引言

2.使用`Github Pages`部署文档

3.使用`Gitalk`添加评论功能

3.1 gitalk介绍

3.2 引入gitalk插件

3.3 申请OAuth application

3.3.1 `关于OAuth application`

3.3.2 申请流程

3.4 gitalk参数说明

3.5 gitalk注意事项

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

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

4.开源项目`README.md`引用

5.总结

6.参考资料

使用docsify构建专业文档网站(下)相关推荐

最新文章

热门文章

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

文章目录

1.引言

2.使用Github Pages部署文档

3.使用Gitalk添加评论功能

3.1 gitalk介绍

3.2 引入gitalk插件

3.3 申请OAuth application

3.3.1 关于OAuth application

3.3.2 申请流程

3.4 gitalk参数说明

3.5 gitalk注意事项

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

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

4.开源项目README.md引用

5.总结

6.参考资料

使用docsify构建专业文档网站(下)相关推荐

最新文章

热门文章

2.使用`Github Pages`部署文档

3.使用`Gitalk`添加评论功能

3.3.1 `关于OAuth application`

4.开源项目`README.md`引用