使用docsify構建專業文檔網站(下)

tags: docsify doc github

---

1.引言

上一篇文章對使用docsify進行文檔網站構建進行了介紹，而且能夠在本地進行訪問。但對於開發者而言，通常都但願本身的文檔，blog或者書籍能夠發佈到網上，進行知識分享，同時能夠評論互動。特別是對軟件進行開源的，通常都配套有對應的說明文檔、幫助文檔、開發文檔等等。而github做爲開發者的彙集地，最適合文檔發佈了。本文將對使用docsify寫好的文檔發佈到github上進行詳細描述。

2.使用Github Pages部署文檔

github有GitHub Pages功能，至關於一個靜態網站的顯示功能，GitHub Pages 支持從三個地方讀取文件:

• 一、master分支
• 二、master分支下的docs目錄
• 三、gh-pages分支

一、若是你的文檔直接是在項目根目錄寫的，那麼可直接把代碼推送到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 的特性：

一、使用 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上的倉庫。

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 50
      distractionFreeMode: false  // Facebook-like distraction free mode
    })
</script>
複製代碼

配置好後，頁面最終效果(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中倉庫讀寫。 詳情介紹：developer.github.com/apps/about-…

3.3.2 申請流程

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

在註冊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 ID
    clientSecret: '4...e',// GitHub Application secret ID
    repo: '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參數是否是必填的選項，可是這個兩個參數很重要建議填上： 一、id參數用於評論記錄和頁面對應的惟一標記，有的時候發現好幾個頁面評論是同樣的，就是因爲配置id參數的時候，這幾個頁面的id是同樣致使。因爲id參數默認值是location.href頁面URL，而有的時候URL中帶着頁面標題的連接，致使URL長度超過了50個字符長度，會致使建立評論issues失敗(長度超過50個會建立失敗)，這點要注意。 二、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 ID
    clientSecret: '4...e',// GitHub Application secret ID
    repo: '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()
      }
    }
複製代碼

說明：

一、因爲docsify的連接URL使用的是hash的方式，致使切換頁面的時候不會刷新頁面，致使整個網站的Gitalk評論使用的是一個評論，所以作了監聽hash事件，來刷新頁面，這樣就能每次切換頁面刷新，而後加載對應的評論。 二、關於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構建專業文檔網站(上)