GitHub Comments for your GitHub Pages

Setup

Quick start

Setup is straightforward – these commits show just how easy it is:

  1. Create a GitHub developer application, so readers trust your site.
  2. Create an instance of Gatekeeper, so readers can login to leave comments.
  3. Add the ghpages-ghcomments files.
  4. Configure comments for your blog.
  5. Add the CSS to your <head>.
  6. Add the comments tag to your post.html layout.
  7. Install the git hooks (skip to step 6 below)

Step-by-step

1. Create a GitHub developer application

  1. Go to your GitHub settings page
  2. Select the Applications item on the left
  3. In the Developer applications panel, select Register new application
  4. Fill in the form:
    • Application name – anything is ok, consider using your site’s title
    • Homepage URL – use the URL to your site
    • Application description – anything is ok, consider using “Comments for [your site’s title]”
    • Authorization callback URL – use the URL to your site
    • Add an application image – consider using your site’s favicon.ico
  5. Once created, you’ll see your Client ID and Client Secret

2. Create an instance of Gatekeeper

These instructions use Heroku, but you can use a different provider (like Azure) or you can use your own server (see Custom GitHub Application for more details).

  1. Prepare Heroku
  2. Clone Gatekeeper:
    • git clone https://github.com/prose/gatekeeper.git
    • cd gatekeeper
  3. Login to Heroku on the command line:
    • heroku login
  4. Create your Heroku app, with your own APP_NAME
    • heroku apps:create APP_NAME
  5. Give your Heroku environment your own XXXX and YYYY GitHub application credentials:
    • heroku config:set OAUTH_CLIENT_ID=XXXX
    • heroku config:set OAUTH_CLIENT_SECRET=YYYY
  6. Deploy your Gatekeeper clone to Heroku:
    • git push heroku master
  7. Check that it’s working:
    • curl https://APP_NAME.herokuapp.com/authenticate/1234
{
  "error": "bad_code"
}

3. Download the ZIP archive and unpack it.

4. Copy the file tree into your Jekyll repository.

5. Edit three files:

_data/gpgc.yml

Specify:

  • your GitHub username for repo_owner
  • your Jekyll repo for repo_name
  • your GitHub application Client ID for client_id
  • your Heroku (or other) application URL for code_authenticator
  • the full URL to gpgc_redirect.html for callback_url
repo_owner: __YOUR_GITHUB_USERNAME__
repo_name: __YOUR_GITHUB_REPOSITORY__
use_show_action: false
label_name: Blog post comments
label_color: 666666
github_application:
  client_id: __YOUR_GITHUB_APP_CLIENT_ID__
  code_authenticator: https://__YOUR_HEROKU_APP__.herokuapp.com/authenticate/
  callback_url: http://__URL_OF_GPGC_REDIRECT_PAGE__
enable_diagnostics: false

If your site is hosted in a private repository, see you can still use ghpages-ghcomments as long as you use a public repository to store the comments. See this post for details.

##

_includes/head.html

Add a link to the gpgc_styles.css to the <head> element:

<link
  rel="stylesheet"
  href="{{ site.baseurl }}/public/css/gpgc_styles.css">

##

_layouts/post.html

Add an include tag at the bottom (or wherever you want comments to appear):

{% include gpgc_comments.html post_title=page.title %}

6. Move _tools/gpgcCreateCommentIssue.sh to your system $PATH.

$ mv _tools/gpgcCreateCommentIssue.sh /usr/local/bin
$ sudo chmod +x /usr/local/bin/gpgcCreateCommentIssue.sh
$ if test -x "`which gpgcCreateCommentIssue.sh`"; then echo ok; fi
ok

7. Install the git hooks. From your repository root:

$ gpgcCreateCommentIssue.sh install <personal_access_token>

Where <personal_access_token> is your GitHub personal API access token. Your token must have the public_repo scope so that the hooks can create labels and issues in your repository.

8. Push to your Jekyll site:

git add _includes/head.html
git add _layouts/post.html
git add _data/gpgc.yml
git add _includes/gpgc_comments.html
git add public/css/gpgc_styles.css
git add public/html/gpgc_redirect.html
git add public/js/gpgc_core.js
git commit -m "Add ghpages-ghcomments"
git push

9. Enable comments for posts you have already published:

$ gpgcCreateCommentIssue.sh bootstrap
$ gpgcCreateCommentIssue.sh push <personal_access_token>

10. New posts now have GitHub comments! See Usage for a refresher or Verbose Usage for more details. If you’re having trouble, see Troubleshooting.

Review

  1. Advantages
  2. Examples
  3. Usage
  4. Options
  5. Setup