Gitalk評論插件使用教程

1. 說明

Gitalk 是一個基於 GitHub Issue 和 Preact 開發的評論插件。

Gitalk 的特性：

一、使用 GitHub 登陸
二、支持多語言 [en, zh-CN, zh-TW, es-ES, fr, ru]
三、支持我的或組織
四、無干擾模式（設置 distractionFreeMode 爲 true 開啓）
五、快捷鍵提交評論 （cmd|ctrl + enter）

使用Gitalk須要你作一些提早準備：
一、在github上建立一個倉庫，Gitalk會把評論放在這個倉庫的issues裏面。
二、在github上申請一個GitHub OAuth application，來讓Gitalk有權限操做github上的倉庫。

2. 安裝使用

2.1 安裝

兩種方式引入：

一、直接在HTML文件中引入

<link rel="stylesheet" href="//cdn.bootcss.com/gitalk/1.5.0/gitalk.min.css">
<script src="//cdn.bootcss.com/gitalk/1.5.0/gitalk.min.js"></script>

建議直接把文件下載後放在項目目錄中，這樣就能夠再也不依賴第三方網絡了。
注意：若是鏈接失效了，請在https://www.bootcdn.cn/上搜索gitalk而後找到對應資源連接複製過來。

二、經過npm安裝

npm i --save gitalk

import 'gitalk/dist/gitalk.css'
import Gitalk from 'gitalk'

2.2 使用

一、首先須要在html文件中添加一個容器，Gitalk組件會在此處顯示

<div id="gitalk-container"></div>

二、使用下面的JavaScript代碼來生成Gitalk評論：

var gitalk = new Gitalk({
  clientID: '2eb19afceda708b27e64', // GitHub Application Client ID
  clientSecret: '36aedb5a30321626a8631689fee5fafd5929f612', // GitHub Application Client Secret
  repo: 'gitalk-comment'      // 存放評論的倉庫
  owner: 'yulilong',          // 倉庫的建立者，
  admin: ['yulilong'],        // 若是倉庫有多我的能夠操做，那麼在這裏以數組形式寫出
  id: location.pathname,      // 用於標記評論是哪一個頁面的，確保惟一，而且長度小於50
})

gitalk.render('gitalk-container');    // 渲染Gitalk評論組件

裏面參數下面會講解。
配置好後，頁面最終效果(https://gitalk.github.io/)：

注意：

一、第一次Gitalk須要初始化評論，須要你先點擊 使用GitHub登錄，而後刷新頁面纔會初始化，或者本身去倉庫裏手動建立一個issues，並添加issues的 labels值爲Gitalk的 labels參數和 id參數的值。

new Gitalk的參數中有github的倉庫信息和GitHub Application信息，因此首先咱們建立這兩個。

在github上建立一個倉庫比較簡單這裏就不講解了。
下面講一下如何申請一個GitHub OAuth application

注意：若是你打算在本身網站使用Gitalk，而且這個網站的源碼在github的倉庫上，那麼你也能夠直接使用這個倉庫，Gitalk只使用倉庫的Issues。

3. 申請一個OAuth application

GitHub OAuth application容許程序來操做你的github帳戶，能夠對github中倉庫讀寫。
詳情介紹：https://developer.github.com/...

申請GitHub OAuth application流程：

一、打開github網站登錄後，點擊右上角的用戶圖標，選擇 Settings
二、 在 Settings頁面選擇 Developer settings選項。
三、在 Developer settings選擇 OAuth Apps,而後會在頁面右邊有一個 New OAuth App按鈕，點擊這個按鈕就進入到新建 OAuth application頁面
四、也能夠直接代開這個連接： https://github.com/settings/a... 進入新建頁面

在註冊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就是咱們須要的參數。

4. Gitalk的參數說明

在上面使用Gitalk的JavaScript代碼中有一些參數：

var gitalk = new Gitalk({
  clientID: '2eb19afceda708b27e64', // GitHub Application Client ID
  clientSecret: '36aedb5a30321626a8631689fee5fafd5929f612',
  repo: 'gitalk-comment'      // 存放評論的倉庫
  owner: 'yulilong',          // 倉庫的建立者，
  admin: ['yulilong'],        // 若是倉庫有多我的能夠操做，那麼在這裏以數組形式寫出
  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參數是否是必填的選項，可是這個兩個參數很重要建議填上：
一、 id參數用於評論記錄和頁面對應的惟一標記，有的時候發現好幾個頁面評論是同樣的，就是因爲配置 id參數的時候，這幾個頁面的id是同樣致使。因爲 id參數默認值是 location.href頁面URL，而有的時候URL中帶着頁面標題的連接，致使URL長度超過了50個字符長度，會致使建立評論issues失敗(長度超過50個會建立失敗)，這點要注意。
二、 title用於在github倉庫issues的標題，若是你想管理評論能夠設置一下這個參數，來區分該評論是來自於那個文章。

其餘參數：

number: 類型：數字，選填，頁面的 issue ID 標識，若未定義number屬性則會使用id進行定位。默認值：-1
labels：類型：數組，選填，GitHub issue 的標籤，默認值：['Gitalk']
body：類型：字符串，選填， GitHub issue 的內容，默認值：URL + HTML中meta標籤中description的值
language：類型：字符串，選填，設置語言，支持 [en, zh-CN, zh-TW]。默認值：navigator.language 或者 navigator.userLanguage
perPage：類型：數字，選填，每次加載的數據大小，最多 100。默認值：10
distractionFreeMode：類型：布爾值，選填，相似Facebook評論框的全屏遮罩效果。默認值：false
pagerDirection：類型：字符串，選填，評論排序方式， last爲按評論建立時間倒敘， first爲按建立時間正序。默認值：last
createIssueManually：類型：布爾值，選填，若是當前頁面沒有相應的 isssue 且登陸的用戶屬於 admin，則會自動建立 issue。若是設置爲 true，則顯示一個初始化頁面，建立 issue 須要點擊 init 按鈕。 默認值：false
proxy：類型：字符串，選填，GitHub oauth 請求到反向代理，爲了支持 CORS。默認值: https://cors-anywhere.herokuapp.com/https://github.com/login/oauth/access_token
flipMoveOptions：類型：對象，選填，評論列表的動畫。 參考
enableHotKey：類型：布爾值，選填，啓用快捷鍵 (cmd/ctrl + enter)提交評論。默認值：true

5. Gitalk實際使用例子

5.1 在docsify中使用

docsify是一個神奇的文檔網站生成工具。詳情介紹請看官網：https://docsify.js.org/#/zh-cn/
使用docsify教程請查看：https://segmentfault.com/a/11...

docsify支持Gitalk評論插件，須要引入一個JavaScript腳本文件：
https://unpkg.com/docsify@4.8.6/lib/plugins/gitalk.min.js

一個實際使用例子：

<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">
  <script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>

  <script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
  <script>
    var gitalk = new Gitalk({
      clientID: '2eb19afceda708b27e64',
      clientSecret: '36aedb5a30321626a8631689fee5fafd5929f612',
      repo: 'gitalk-comment',
      owner: 'yulilong',
      admin: ['yulilong'],
      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()
      }
    }
    // 因爲docsify/lib/plugins/gitalk.min.js文件中已經有下面代碼了，因此不須要在寫一次了
    // gitalk.render('gitalk-container')
  </script>

說明：

一、因爲docsify的連接URL使用的是hash的方式，致使切換頁面的時候不會刷新頁面，致使整個網站的Gitalk評論使用的是一個評論，所以作了監聽hash事件，來刷新頁面，這樣就能每次切換頁面刷新，而後加載對應的評論。
二、關於Gitalk參數 id的值，因爲點擊二級標題後，二級標題會以參數的形式出如今url上，致使長度有事超過了50，因此過濾掉URL中的參數，此外還能解決評論定位不到問題(二級標題會在URL上)。

5.2 在VuePress中使用

關於VuePress，請參考：https://vuepress.vuejs.org/zh/

咱們須要建立.vuepress/enhanceApp.js文件，內容以下：

function integrateGitalk (router) {
    const linkGitalk = document.createElement('link');
    linkGitalk.href = 'https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.css';
    linkGitalk.rel = 'stylesheet';
    document.body.appendChild(linkGitalk);
    const scriptGitalk = document.createElement('script');
    scriptGitalk.src = 'https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js';
    document.body.appendChild(scriptGitalk);
    var path = '';

    router.afterEach((to) => {
        if (scriptGitalk.onload) {
            setTimeout(loadGitalk, 5, to)
        } else {
            scriptGitalk.onload = () => {
                loadGitalk(to.fullPath);
            }
        }
    });

    function loadGitalk (to) {
        if (to.path !== path) {
            path = to.path;
            let commentsContainer = document.getElementById('gitalk-container');
            const $page = document.querySelector('.page');
            if (commentsContainer && $page) {
                $page.removeChild(commentsContainer)
            }
            commentsContainer = document.createElement('div');
            commentsContainer.id = 'gitalk-container';
            commentsContainer.classList.add('content');
            if ($page) {
                $page.appendChild(commentsContainer);
                if (typeof Gitalk !== 'undefined' && Gitalk instanceof Function) {
                    renderGitalk();
                }
            }
        }
    }
    function renderGitalk () {
        const gitalk = new Gitalk({
            clientID: '2eb19afceda708b27e64',
            clientSecret: '36aedb5a30321626a8631689fee5fafd5929f612',
            repo: 'gitalk-comment',
            owner: 'yulilong',
            admin: ['yulilong'],
            title: location.pathname,
            id: location.pathname,      // Ensure uniqueness and length less than 50
            language: 'zh-CN',
        });
        gitalk.render('gitalk-container');
    }
    window.loadGitalk = loadGitalk;
}

export default ({ Vue, options, router }) => {
    try {
        document && integrateGitalk(router)
    } catch (e) {
        console.error(e.message)
    }
}

保存文件後，重啓vuePress服務便可。
效果以下圖：

參考資料

Gitalk 官網
Gitalk中文文檔