iBlog：基於Gracejs及github issues的全功能博客方案

iBlog 是徹底基於github API 並充分利用 gracejs 數據代理特性實現的全功能博客方案。

• 項目地址： github.com/xiongwilee/…
• 體驗地址： iblog.wilee.me (訪問比較慢是由於用的最最低配的aws ECS服務)

簡介

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：

一、生成Personal Access Token：

若是你已經有了可使用的token，則直接跳到「二、在Gracejs中配置token」。

• 首先，登陸github以後訪問：github.com/settings/to… ；
• 而後，在「Token description」下填寫token，「scopes」選擇repo、user；
• 而後，點擊「Generate token」，複製保存生成40個字節長度的token，以下：
  

  

  token

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

二、在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 ， 就能夠看到默認頁面了！

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]: 圖片連接

參考：

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。