iBlog：基於Gracejs及github issues的全功能部落格方案

Wilee發表於2017-04-06
JSGithub

iBlog 是完全基於github API 並充分利用 gracejs 資料代理特性實現的全功能部落格方案。

簡介

github作為全球最大同性交友網站，已經有人在其上面做了很多匪夷所思的事情，利用issues功能寫部落格就是其中之一……

背景

現在已經有一些開源的基於github issues的部落格系統了，例如: cms.js等。但這些在客戶端（瀏覽器）對github api呼叫的實現方案，有幾個問題：

  1. github api 在不使用token訪問的情況下有根據IP每小時60個請求的限制；
  2. 在瀏覽器端呼叫介面，沒法實現使用者登入和評論；
  3. 總所周知的原因，國內訪問github非常不穩定，甚至部分地區直接無法訪問；

聯想到Gracejs強大的資料代理的特性，我們能不能直接在服務端呼叫github api，實現一套部落格系統呢？

這樣的話，我就可以把我github repo的issues作為部落格的管理後臺；甚至可以利用github issues comments的api及 github oauth 2.0 的api來實現評論系統，就再也不用擔心類似多說停止服務的問題了！

特性

當然了，你看到了這篇文章，說明這個方案實現了：iBlog：基於Gracejs及github issues的全功能部落格方案 。其主要特性如下：

  1. 基於Gracejs + github issues實現，不依賴任何資料庫；
  2. 具備部落格、分類、評論等功能，並與github issues保持同步；
  3. 服務端呼叫github api，不用擔心github api訪問不穩定的問題；
  4. 僅展示repo擁有者的issues，完全不用擔心issues被惡意篡改的問題；
  5. 頁面響應式支援，手機或其他客戶端訪問體驗更加；

快速開始

iBlog原始碼獨立託管在 xiongwilee/iblog ，但為了演示簡便，在Gracejs裡已經預設整合了iBlog的產出檔案；所以，接下來直接利用Gracejs帶你快速啟動iBlog。

安裝

環境依賴：請務必確保你環境裡的Nodejs版本是7.6.0+。

第一步，下載Gracejs並安裝依賴：

# koa-grace即Gracejs
$ git clone git@github.com:xiongwilee/koa-grace.git
$ cd koa-grace
$ npm install複製程式碼

FYI：小白同學可以注意幾點：

  1. 如果不會用git clone命令，你可以直接點選Gracejs主頁的Clone or download按鈕，然後點選Download ZIP；
  2. 使用cnpm或者yarn安裝，體驗會更佳；

第二步，啟動服務：

# 請保持在koa-grace目錄下執行
$ npm run dev複製程式碼

然後，用瀏覽器開啟 https://0.0.0.0:3000 ，這時候瀏覽器提示：Personal Access Token Undefined! 則表示服務正確啟動，但沒有配置github personal token。

第三步，配置token：

1、生成Personal Access Token：

如果你已經有了可以使用的token，則直接跳到“2、在Gracejs中配置token”。

  • 首先，登入github之後訪問：github.com/settings/to… ；
  • 然後，在“Token description”下填寫token，“scopes”選擇repo、user；
  • 然後，點選“Generate token”，複製儲存生成40個位元組長度的token，如下：
    iBlog：基於Gracejs及github issues的全功能部落格方案
    token

FYI：請儲存好這個token，以後不會再在這個頁面上看到了。

2、在Gracejs中配置token

將你獲取到的token複製下來之後，回到koa-grace的目錄。貼上到koa-grace/config/main.development.js下的constant.token裡：

  // 通用引數，以模板引數的形式傳遞給模板引擎
  constant: {
    cdn: '',
    domain: {
      demo: 'https://127.0.0.1:3000'
    },
    // github personal token ，不知道這個配置，完全可以忽略它
    token: "在這裡貼上你剛剛獲取到的token" 
  },複製程式碼

FYI：

  1. 請不要把這裡的token提交到github倉儲，因為github有安全措施：如果你提交的程式碼中存在你的token，則會自動把你建立的token刪掉！
  2. github api v3版有個限制（參考：developer.github.com/v3/#rate-li…）：在不配置token的情況下僅允許單個IP每小時60次請求的限制；配置token之後，單個token每小時限制5000次，對個人部落格來說足夠了。

第四步，完成！

儲存之後可以在剛剛npm run dev的控制檯看到服務已經自動重啟。這時候再訪問：https://0.0.0.0:3000 ， 就可以看到預設頁面了！

iBlog：基於Gracejs及github issues的全功能部落格方案
blog

BTW：如果這時候看不到這個頁面，那麼很有可能是你根本訪問不了github，R.I.P.

配置

除了上述的token的配置之外，iBlog還支援其他配置；其他配置的檔案在koa-grace/app/iblog/controller/base.js中的config變數。

FYI：以下配置請保持你的服務處於正常啟動的狀態。

owner及repo配置

owner及repo配置及配置文章來源的倉儲，在koa-grace/app/iblog/controller/base.js中的預設配置是：

owner: 'xiongwilee', // github使用者名稱
repo: 'blog'          // 作為文章源的github倉儲複製程式碼

也就是預設使用github.com/xiongwilee/… 下的issues作為文章源。你需要配置為你自己的github使用者名稱及用以承載部落格的github倉儲。

配置完儲存之後，服務自動重啟；這時候開啟頁面，看到的就是自己repo的issues 裡的內容了（如果沒有repo issue則提示“沒有文章”）。

FYI：這裡獲取文章（即你配置的repo裡的issues）的規則是：1）該issue必須是你親自建立的；2）該issue必須是open狀態

右邊欄友情連結配置

右邊欄友情連結的配置非常簡單，在base.js中的site.links中，根據你的需求配置即可。

文章分類配置

在右邊欄有一個labels，即文章分類。這裡的文章分類直接讀取你配置的github repo的labels配置。

以預設的配置xiongwilee/blog為例，你可以在這裡管理Labels：github.com/xiongwilee/…。

然後，你可以在github上的issues詳情頁配置文章的Labels（即文章分類） 參考：[github.com/xiongwilee/…

文章簡介、主題圖片配置

接下來，所有的文章就直接通過你配置的github repo的issues來管理了。這裡請再次注意：必須是你親自建立而且是open狀態的issue才會在你的blog中展示 。

在首頁的文章列表的文章有兩種元素：1）文章簡介；2）文章主題圖片。這兩種元素分別在 issue的markdown內容的頂部宣告：

  • 文章簡介語法：[intro]: 文章簡介
  • 文章主題圖片語法：[image]: 圖片連結

參考：

iBlog：基於Gracejs及github issues的全功能部落格方案
intro

oauth配置

配置oauth的主要目的是為了獲取登入使用者的資訊及通過github api發表文章評論。

其大致原理是：首先使用者通過github登入，然後通過使用者登入github時access_token儲存到cookie，然後就可以通過這個access_token獲取當前登入使用者的資訊及發表評論。

這裡大致介紹怎麼配置oauth。

第一步，獲取client_id和client_secret

登入github之後訪問github.com/settings/de…，點選Register a new application。

在“Register a new OAuth application”頁面中：

  • “Application name”、“Homepage URL”、“Application description”根據英文提示填寫即可；
  • “Authorization callback URL”填寫登入成功之後的回撥連結。例如，iblog.wilee.me的配置是：https://iblog.wilee.me/user/oauth?from=github；你本地服務的配置則是：https://0.0.0.0:3000/user/oauth?from=github。

點選“Register application”建立client_id和client_secret對。

第二步，配置client_id和client_secret

配置client_id和client_secret非常簡單，在base.js中配置即可：

  // OAuth applications clientId & clientSecret
  client_id: '你生成的client_id',
  client_secret: '你生成的client_secret',複製程式碼

儲存之後，服務自動重啟；在本地服務的任意一個文章詳情的底部，則可以通過“login with github”按鈕登入，登入之後會會跳到文章詳情頁，這時候看到的就是登入狀態，就可以評論了。

BTW：這裡的評論和這篇文章對應的repo 裡issues的評論是一一對應的。

開發

上述是所有對iBlog配置的概述，如果你僅僅想簡單使用這個部落格系統，看到這裡就行了。但如果你想進一步開發，做更加個性化的深度訂製的話，可以繼續往下看。

FYI：以下操作請保持Gracejs服務啟動（即在koa-grace目錄下npm run dev為執行狀態），並重新開一個命令列視窗操作。

下載iBlog原始碼

請再次注意，保持koa-grace為啟動狀態，並在koa-grace路徑下執行：

# 到koa-grace的同級路徑下
$ cd ../
# 下載iBlog真正的原始碼
$ git clone git@github.com:xiongwilee/iblog.git
$ cd iblog
$ npm install複製程式碼

啟動檔案監聽

iBlog業務實現基於 gulp+require.js+less+Nunjucks ，在iblog路徑下執行npm run dev啟動開發模式下檔案監聽：

# 保持在iblog路徑下
$ npm run dev複製程式碼

這時候你可以根據自己的需求訂製iblog了。開發過程中，產出的檔案就會通過gulp自動編譯，產出到koa-grace/app/iblog目錄中。

檔案打包

如果開發完成，在iblog路徑下執行npm run build即可。有興趣的同學可以自行對比下npm run dev和npm run build產出檔案的差異。

TODO

  • 基於reveal.js 直接把文章生成slides；
  • 更友好的labels分類頁面，提示當前是在那個label下；
  • 文章自動生成大綱的功能；

貢獻

iBlog的實現非常倉促，從有了iBlog這個idea到詳細構思、到設計、到開發一共就三天時間，難免會有BUG；歡迎到 github.com/xiongwilee/… fork參與開發，或者賞個star。

相關文章