gitbook 入门教程之实用插件(新增3个插件)

时间  2019-12-01
标签 gitbook 入门 教程 之实 插件 新增 栏目 Git 繁體版
原文   原文链接

插件没有什么逻辑顺序,你们能够按照目录大纲直接定位到感兴趣的插件部分阅读便可.css

更多插件正在陆续更新中,敬请期待...html

最新更新插件

  • tbfed-pagefooter 版权页脚插件
  • gitalk 评论插件
  • search-plus 中文搜索插件

gitalk 评论插件并非 gitbook 插件,于是集成方式和通常的插件安装方式不一样!node

若是但愿将网页源码暴露出去并接受公众的监督校准的话,使用edit-link插件能够直接连接到源码文件.git

连接地址: https://plugins.gitbook.com/plugin/tbfed-pagefootergithub

gitbook-plugin-tbfed-pagefooter-preview.png

激活插件配置

在 book.json 中配置 tbfed-pagefooter 插件,详细说明请参考 tbfed-pagefooter 插件.web

示例:npm

{
    "plugins": ["tbfed-pagefooter"],
    "pluginsConfig": {
        "tbfed-pagefooter": {
          "copyright":"&copy snowdreams1006",
          "modify_label": "文件修订时间：",
          "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    }
}

示例:json

$ gitbook install

启动本地服务后,每一个页面的页脚处都会自动生成版权信息以及当前文件的最后更新时间.服务器

功能慎用: 若是文档频繁更新适合生成最后更新时间,若是长时间不更新文档,岂不是最后更新时间仍是几年前,给读者的感受像是再也不维护了同样!微信

示例:

$ gitbook serve

gitbook-plugin-tbfed-pagefooter-preview.png

disqus 评论插件

discus 是一款集成评论的插件,能够为静态网站添加动态评论,让你的网站动起来!

gitbook-plugin-disqus-success-with-FQ.png

遗憾的是,discus 插件只有 FQ 才能正常使用,暂时没找到其余较好的替代方案.

注册 disqus.com 帐号

gitbook 集成 disqus 插件中最重要的配置项就是注册 disqus.com 网站惟一标识.

gitbook-plugin-disqus-preview.png

注册并绑定域名

若是没有注册帐号请先注册,不然直接登陆,固然也支持第三方帐号登陆(我使用的是谷歌帐号).

gitbook-plugin-disqus-login.png

人机验证时,选出符合条件的所有图形,直到没有新的图形为止,这一点和国内的静态图片验证是不一样的!

选择安装 disqus 插件(I want to install Disqus on my site),接下来会绑定集成网站的域名.

gitbook-plugin-disqus-goal.png

接下来设置网站的相关信息,其中网站名称(snodreams1006)是惟一标示,接下来集成到 gitbook 用的就是这个简短名称,而分类和语言按照实际状况选择便可.

gitbook-plugin-disqus-create-site.png

选择服务类型

disqus 网站提供的服务类型,有基础班(basic),增强版(plus),专业版(pro)和免费版(free).

每一个版本计划有不一样的收费标准以及相应的服务,能够根据实际状况选择适合本身的服务类型.

gitbook-plugin-disqus-select-plan.png

接下来以避免费版为例进行有关演示

gitbook-plugin-disqus-free-selected.png

安装并配置 disqus 到网站

估计是这些网站提供了默认的集成方式,这里并没看到 gitbook 相关的网站,所以选择最后一个自定义网站.

gitbook-plugin-disqus-install-website.png

填写网站的基本信息,其中网站缩写名称仍然是 snowdreams1006,网址填写 https://snowdreams1006.github.io/ ,至于其余信息根据实际状况填写便可.

gitbook-plugin-disqus-config-site.png

至此 disqus.com 网站配置完成,接下来咱们配置 gitbook 集成 disqus 插件.

gitbook-plugin-disqus-complete.png

安装并配置 disqus 插件

上一步咱们已经获取到惟一的标识: snowdreams1006 ,接下来能够继续配置 disqus 插件了.

连接地址: https://plugins.gitbook.com/plugin/disqus

激活插件配置

在 book.json 中配置 disqus 插件,根据实际状况修改为本身的缩写名称(shortName).

示例:

{
    "plugins": ["disqus"],
    "pluginsConfig": {
        "disqus": {
            "shortName": "snowdreams1006"
        }
    }
}

安装 disqus 插件

示例:

$ gitbook install

测试 disqus 插件

示例:

$ gitbook serve

正常状况下(FQ),disqus 插件已经成功集成到 gitbook 网站了,所以推送到实际服务器上时看到的效果是这样的.

gitbook-plugin-disqus-success-with-FQ.png

若是你不具有条件(FQ),那么你看到的仍然是这样的.

gitbook-plugin-disqus-success-without-FQ.png

gitalk 评论插件

本篇文章发表在开源中国后获得网友 @八一菜刀 的评论,让我推荐了gitalk 评论插件,初始使用了一下,确实不错,所以在这里更新下.

上述 disqus 评论插件虽然比较好用,可是注册是在 disqus.com 官网,须要特殊手段才能访问,即使成功配置了国内通常也是访问不到的,所以功能至关鸡肋.

gitalk 评论插件解决了这一痛点,利用 github 的开发者接口受权,将讨论区的 issue 变成评论区,和 github 结合的如此紧密,适合用源码托管到 github 这类状况.

先混个脸熟,看一下 gitalk 官网 是如何介绍本身的呢.

gitbook-plugin-gitalk-preview.png

看着效果确实不错,而且评论区的内容直接做为 github 仓库的 issue,这么好的想法我咋没想到呢!

好了,如今让咱们开始集成到咱们本身的项目中,遇到新鲜事物,固然先要参考官网介绍了.

申请 GitHub Application 受权

登陆 github 帐号,点击 在线申请 受权应用.

看到这一步,想必读者已经有个大概印象了,gitalk 插件是利用 github 的开发者服务,进行受权进而调用 issue 相关接口从而显示评论功能.

这种由官网提供的开发者服务仍是比较好的,至少感受比手动模拟提交要靠谱些,更况且走的是 OAuth 受权模式.

好比第三方应用提供微信登陆,走的也是 OAuth 协议,这里的第三方应用固然就是如今说的 Gitalk
插件,微信就是咱们的 github .

新建应用,首页 url 和受权回调 url 填写相同的首页连接便可,其余状况自定义填写.

gitbook-plugin-gitalk-register-application.png

应用登记成功后会生成 token 令牌,clientId 和 clientSecret 须要重点保存下来,待会须要用到.

gitbook-plugin-gitalk-generate-token.png

安装并集成到网站

在须要添加评论的页面,添加下述内容引入 gitalk 插件,其中参数来自咱们上一步获取的 clientId 和 clientSecret .

默认应该添加到 .html 页面,固然也能够添加到 .md 页面,毕竟 markdown 语法也支持 html 标签.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.css">
<script src="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js"></script>
<div id="gitalk-container"></div>
var gitalk = new Gitalk({
  "clientID": "clientId",
  "clientSecret": "clientSecret",
  "repo": "GitHub repo",
  "owner": "GitHub repo owner",
  "admin": ["GitHub repo admin"],
  "id": location.pathname,      
  "distractionFreeMode": false  
});
gitalk.render("gitalk-container");

稍微解释下参数的含义:

  • "clientID" : [必选] GitHub Application Client ID
  • "clientSecret" : [必选] GitHub Application Client Secret
  • "repo" : [必选] GitHub repository
  • "owner" : [必选] GitHub repository 全部者，能够是我的或者组织
  • "admin" : [必选] GitHub repository 的全部者和合做者 (对这个 repository有写权限的用户)
  • "id" : [可选] 页面的惟一标识,默认值: location.href, 长度必须小于50,不然会报错!
  • "distractionFreeMode": [可选] 相似 Facebook 评论框的全屏遮罩效果,默认值: false

上述配置只是最简配置,若是想要了解更多高级配置,请参考 官方文档

测试集成效果

按照上述安装步骤,将代码复制到首页(README.md)文件中,而后推送到 github ,体验下集成效果.

注意: 这里必须推送到服务器,由于申请应用时填写的域名是线上地址,于是本地测试是不会成功的,会报错,这一点和微信支付的回调地址相似.

示例:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.css">
<script src="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js"></script>
<div id="gitalk-container"></div>
var gitalk = new Gitalk({
  "clientID": "3f62415a283d19cbd696",
  "clientSecret": "aed0e1db0620bf5d0e3a3f0225f801997ad74e58",
  "repo": "snowdreams1006.github.io",
  "owner": "snowdreams1006",
  "admin": ["snowdreams1006"],
  "id": location.pathname,      
  "distractionFreeMode": false  
});
gitalk.render("gitalk-container");

上述参数仅供参考,实际使用中请替换成本身的配置,否则你也没有我仓库的权限,确定会报错的啊!

gitbook-plugin-gitalk-init-issue.png

心心相念的 gitalk 评论区呢?是否是哪里配置错了,为啥没有出来?

别急,要淡定,看一下提示说"未找到的 Issue 进行评论,请联系 @snowdreams1006 初始化建立",既然如此,那咱们就操做一下吧!

点击下方的按钮 使用 Github登陆 ,会跳转到相应的仓库,而后按照提示肯定.

再次返回首页,刷新一下看看发生什么神奇的事情了?

gitbook-plugin-gitalk-index-success.png

终于集成了评论功能,并且还支持 markdown 格式的评论呢!

进一步思考

确实不错,心中天然是欣喜万分,但别高兴太早了,由于你会发现其余页面并无评论区,也很好理解,咱们目前仅仅在首页(README.md) 集成了 gitalk 插件,也就是说使用 gitbook build 输出的 index.html 首页才支持评论区,其余页面没有插入上述代码,天然是没有评论区功能的啊!

那若是想要实现全网站的全部页面都集成评论区功能,应该怎么办呢?

百度搜索了一下,并无找到优雅的解决方案,若是有人可以提供更好的解决方案,还望不吝赐教,在此谢过.

既然网上找不到优雅的解决方案,那寻求专业人士的帮助也是一种好办法,我去哪找 gitalk 的使用者呢?

聪明的你或许已经想到了,解铃还须系铃人,固然是向推荐给我插件的大牛提问了!

他确实提供了一种思路,如下是网友@八一菜刀原话:

文档里面我用的是tbfed-pagefooter插件，不过我是在本地使用gitbook install后重写了该插件的js，无非就是在js里面加一段Gitalk的调用代码，这样使用gitbook build命令的时候，全部的页面都会有Gitalk的评论调用

人家既然已经提供了思路,不太好意思继续麻烦人家要源码,既然如此,那就本身动手吧!

tbfed-pagefooter 插件很熟悉,通常是用于注明版权以及文章的修订时间的,并且做用于每一个页面,这一点就知足了集成 gitalk 相关代码的基本要求.

大致方向肯定后,目前就是解决如何在 tbfed-pagefooter 插件构建的相关生命周期内顺便执行咱们的代码?

正常当前项目安装 tbfed-pagefooter 插件后应该存放于 /node_modules/gitbook-plugin-tbfed-pagefooter 目录,大体看一下插件的项目结构.

gitbook-plugin-tbfed-pagefooter
├── LICENSE
├── README.md
├── assets
│   └── footer.css
├── index.js
└── package.json

1 directory, 5 files
$

为了基本看懂项目文件做用,特地去看了下 gitbook 插件开发文档,目标锁定在 index.js .

截取重要片断,原来是电子书构建前动态增长了 html 片断啊,这就好办了!

hooks: {
    'page:before': function(page) {
      var _label = '最后更新时间: ',
          _format = 'YYYY-MM-DD',
          _copy = 'powered by snowdreams1006'
      if(this.options.pluginsConfig['tbfed-pagefooter']) {
        _label = this.options.pluginsConfig['tbfed-pagefooter']['modify_label'] || _label;
        _format = this.options.pluginsConfig['tbfed-pagefooter']['modify_format'] || _format;

        var _c = this.options.pluginsConfig['tbfed-pagefooter']['copyright'];
        _copy = _c ? _c + ' all right reserved，' + _copy : _copy;
      }
      var _copy = '<span class="copyright">'+_copy+'</span>'
      var str = ' \n\n<footer class="page-footer">' + _copy +
        '<span class="footer-modification">' +
        _label +
        '\n{{file.mtime | date("' + _format +
        '")}}\n</span></footer>'

      str += '\n\n<link rel="stylesheet" href="https://unpkg.com/gitalk/dist/gitalk.css">'+
      '\n\n<script src="https://unpkg.com/gitalk@latest/dist/gitalk.min.js"></script>'+
      '\n\n<div id="gitalk-container"></div>'+
      '\n\n<script src="https://snowdreams1006.github.io/gitalk-config.js"></script>';

      page.content = page.content + str;
      return page;
    }
  },

看懂基本原理后顺便修改了版权说明以及修订时间格式,而后追加了集成 gitalk 的相关代码.

这里为了方便修改 gitalk 配置,特地将相关配置项单独托管到 github 专门的 gitalk-config.js 文件.

至于配置文件的内容,并没什么特殊之处,仍是顺便贴一下吧!

var gitalk = new Gitalk({
  "clientID": "3f62415a283d19cbd696",
  "clientSecret": "aed0e1db0620bf5d0e3a3f0225f801997ad74e58",
  "repo": "snowdreams1006.github.io",
  "owner": "snowdreams1006",
  "admin": ["snowdreams1006"],
  "id": window.location.pathname,
  "distractionFreeMode": false
});
gitalk.render("gitalk-container");

至此,以后再本地构建电子书时(gitbook build),gitbook-plugin-tbfed-pagefooter 天然会顺便帮咱们运行集成 gitalk 的相关代码,这才是相对来讲比较优雅的作法.

固然也不必定非要借助 gitbook-plugin-tbfed-pagefooter 插件帮忙,也能够借助别的插件进行集成,甚至本身写个更好的插件.

小结

gitalk 插件相对 disqus 插件来讲,更符合基本国情,只不过默认的集成方式只能一个页面一个页面去集成,当数量比较多时,工做量不敢想象.

所以,经过 gitbook 插件开发的方式,在源码文件输出为目标文件时加入相关集成代码,至关于手写100条输出语句和循环写100条输出语句.

其实本质上并无改变什么,仍然是集成到每一个页面中,可是简化了人工操做的工做量就是效率的提高.

若是有更高效更优雅的集成方式,欢迎你们一块儿探讨.

若是但愿将网页源码暴露出去并接受公众的监督校准的话,使用edit-link插件能够直接连接到源码文件.

连接地址: https://plugins.gitbook.com/plugin/edit-link

gitbook-plugin-edit-link-preview.gif

激活插件配置

在 book.json 中配置 edit-link 插件,详细说明请参考 edit-link 插件.

示例:

{
    "plugins": ["edit-link"],
    "pluginsConfig": {
        "edit-link": {
          "base": "https://github.com/snowdreams1006/snowdreams1006.github.io/blob/master",
          "label": "编辑本页"
        }
    }
}

示例:

$ gitbook install

若是不能正常跳转到源码文件,屡次试验后从新更改 edit-link.base 节点内容,从新 gitbook serve 便可正常跳转源码文件.

示例:

$ gitbook serve

gitbook-plugin-edit-link-preview.png

github 插件

添加 github 图标连接,方便直接跳转到 github 指定仓库.

连接地址: https://plugins.gitbook.com/plugin/github

gitbook-plugin-github-preview.png

激活插件配置

在 book.json 中配置 github 插件,详细说明请参考 github 插件.

示例:

{
    "plugins": ["github"],
    "pluginsConfig": {
        "github": {
          "url": "https://github.com/snowdreams1006/snowdreams1006.github.io"
        }
    }
}

安装 github 插件

示例:

$ gitbook install

测试 github 插件

示例:

$ gitbook serve

gitbook-plugin-github-preview.png

search-plus 中文搜索插件

默认的 search 搜索插件是不支持中文搜索的,而 search-plus 则功能更强大些,二者不能共存,须要禁用或移除 search 插件.

连接地址: https://plugins.gitbook.com/plugin/search-plus

gitbook-plugin-search-plus-preview.png

激活插件配置

在 book.json 中配置 github 插件,详细说明请参考 github 插件.

示例:

{
    "plugins": [
      "-lunr", 
      "-search", 
      "search-plus"
    ]
}

安装 search-plus 插件

示例:

$ gitbook install

测试 search-plus 插件

测试是否可以进行中文搜索,若是不能,请确保已移除默认的 "lunr" 和 "search" 插件.

示例:

$ gitbook serve

gitbook-plugin-search-plus-preview.png

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程