最近在用 VuePress 寫文件。為了更好地和別人交流，決定加上一個評論外掛。考慮到評論外掛要和 GitHub issues 整合，最後篩選出 Gitman 和 Gitalk. 因為前者年代久遠經久失修，而後者的口碑還不錯，遂選擇了 Gitalk。這裡把搭建 Gitalk 的流程以及坑貼出來。
目前 VuePress 的穩定版是 0.44.x，不過這裡我們直接用 1.0.0-alpha.44，因為穩定版功能實在是太爛了... 關於安裝 Vuepress 及配置這裡不詳細說，具體請看 官方文件。
網上有一些教程使用 enhanceApp 建立 Gitalk， 但此方法有 bug，即切換頁面時 Gitalk 不更新，所以我們使用元件註冊的方式。
註冊 OAuth
登入你的 GitHub 並開啟 OAuth Application，點選右上角的按鈕 New OAuth App 填寫表單。
注意 Application name 一定寫成 gitalk.
Authorization callback URL 一定要填專案實際的 URL（很重要）.
註冊成功後你會得到一個 Client ID 和 Client Secret. 理論上密碼可以暴露出來，因為 Authorization callback URL 唯一指向了你設定的回撥 URL，所以別人拿到了私鑰也不能怎樣。
評論元件
我們回到工程，在 docs/.vuepress 下新建一個資料夾 components，再在 components 資料夾下建一個 comment 資料夾，然後新建檔案 comment.vue，並複製下面的程式碼。
<template>
<div class="gitalk-container">
<div id="gitalk-container"></div>
</div>
</template>
<script>
export default {
name: 'comment',
data() {
return {};
},
mounted() {
let body = document.querySelector('.gitalk-container');
let script = document.createElement('script');
script.src = 'https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js';
body.appendChild(script);
script.onload = () => {
const commentConfig = {
clientID: 'YOUR_CLINENT_ID',
clientSecret: 'YOUR_CLINENT_SECRET',
repo: '此倉庫的名稱',
owner: '你的 GitHub 使用者名稱，注意是使用者名稱！！！',
// 這裡接受一個陣列，可以新增多個管理員
admin: ['你的 GitHub 使用者名稱'],
// id 用於當前頁面的唯一標識，一般來講 pathname 足夠了，
// 但是如果你的 pathname 超過 50 個字元，GitHub 將不會成功建立 issue，此情況可以考慮給每個頁面生成 hash 值的方法.
id: location.pathname,
distractionFreeMode: false,
};
const gitalk = new Gitalk(commentConfig);
gitalk.render('gitalk-container');
};
},
};
</script>
複製程式碼配置元件
在工程根目錄下新建一個資料夾 builds，並在裡面新建三個檔案，分別是 findMarkdown.js, addComponents.js 和 delComponents.js.
findMarkdown.js
這個檔案讀取你所有的 Markdown 檔案的內容。
const fs = require('fs')
function findMarkdown(dir, callback) {
fs.readdir(dir, function (err, files) {
if (err) throw err
files.forEach((fileName) => {
let innerDir = `${dir}/${fileName}`
if (fileName.indexOf('.') !== 0) {
fs.stat(innerDir, function (err, stat) {
if (stat.isDirectory()) {
findMarkdown(innerDir, callback)
} else {
callback(innerDir)
}
})
}
})
})
}
module.exports = findMarkdown
複製程式碼addMarkdown.js
此檔案將 comment 元件註冊到每個 Markdown 檔案的最後。
const fs = require('fs')
const findMarkdown = require('./findMarkdown')
const rootDir = './docs'
findMarkdown(rootDir, writeComponents)
function writeComponents(dir) {
fs.appendFile(dir, `\n \n <comment-comment/> \n `, (err) => {
if (err) throw err
console.log(`add components to ${dir}`)
})
}
複製程式碼delMarkdown.js
此檔案在編譯後執行，目的是將每個 Markdown 檔案的 comment 元件移除，因為我們只想讓 comment 元件打包到編譯後的檔案中，而非工程檔案。
const fs = require('fs')
const findMarkdown = require('./findMarkdown')
const rootDir = './docs'
findMarkdown(rootDir,delComponents)
function delComponents(dir){
fs.readFile(dir,'utf-8', (err, content) => {
if (err) throw err
fs.writeFile(dir, content.replace(/\n \n <comment-comment\/> \n /g,''), (err) => {
if (err) throw err
console.log(`del components from ${dir}`)
})
})
}
複製程式碼修改 package.json
因此我們需要修改 build 的執行指令碼。
build: "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js"
複製程式碼去 GitHub 檢查一下
構建並部署到伺服器上之後，任意開啟一個頁面，Gitalk 會自動將此頁面註冊到 GitHub issues（這也是我們不選擇 Gitman 的原因，Gitman 必須人肉新增）。