Ghost Blog on GitHub Pages

PUBLISHED ON AUG 12, 2014 — TUTORIAL

Static Ghost Blog? The answer you’re looking for is Buster.

Buster is a Super simple, Totally awesome, Brute force static site generator for Ghost.

It creates a static version of your Ghost blog which you can then upload to your server or any other destination of your choosing.

Why Static Ghost?

There are many advantages to having a static Ghost blog:

  • You can host your blog anywhere since you won’t have to worry about whether your host supports Node.js.
  • No database, everything is static.
  • Better security, no backend to hack into.
  • Better performance, static sites load faster.
  • You can easily backup your blog, simple copy-and-paste will do the trick.
  • You can work offline. Write a post or test changes locally, then generate the static version and upload it to your server.
  • And best of all, you can host your blog for free on GitHub Pages.

Overview

Feel free to skip to any section:

  1. Create GitHub Pages repo
  2. Install Ghost Locally
  3. Install Buster
  4. Introduction to Buster
  5. Generate Static Ghost Blog
  6. Making Changes to your Blog

Create GitHub Pages repo

Head over to GitHub and create a new repository named: username.github.io, where username is your username on GitHub.

If the first part of the repository doesn’t exactly match your username then it won’t work, so make sure to get it right.

My username on GitHub is mtalalanwar, therefore the name that I entered for my repo was mtalalanwar.github.io

Install Ghost Locally

Make sure that you have git and nodejs installed on your local machine prior to installing Ghost.

Installing Ghost is a very straightforward process.

Get a copy of the latest version of Ghost:

cd ~/Documents
curl -L https://ghost.org/zip/ghost-latest.zip -o ghost.zip
unzip ghost.zip -d ghost

I decided to set up Ghost in my Documents folder, you are free to choose any directory you want.

Before you can install Ghost, you need to make some changes to the config.js file:

cd ~/Documents/ghost
cp config.example.js config.js
nano config.js

Navigate to the development section and change the url: from http://localhost:2368 to http://username.github.io.

Now, to install Ghost. Make sure that you are in the right directory: cd ~/Documents/ghost, and then:

npm install

This might take a while, just be patient and let Ghost install all of its dependencies.

After the installation is complete, go ahead and start Ghost:

npm start

You should get an output similar to this:

> ghost@0.3.3 start /Users/EliteZERO/Documents/ghost
> node index

Ghost is running...
Listening on 127.0.0.1:2368
Url configured as: http://example.com
Ctrl+C to shut down

This means that Ghost has been installed correctly and is working as it should.

Go to http://127.0.0.1:2368/ghost/, there you should be able to see your new Ghost blog.

Install Buster

In order to install Buster, you need to have wget and python installed on your machine.

If you are on a Mac then you can do this using Homebrew.

Install Homebrew:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

The script explains what it will do and then pauses before it does it.

Install Buster prerequisites:

brew install wget python

Now, go ahead and install Buster:

pip install --upgrade pip
pip install buster

Introduction to Buster

Here is an overview of the various Buster commands and what they do:

  • buster setup [--gh-repo=<repo-url>]: Makes a static/ directory and initializes a Git repository inside it.
  • buster generate [--domain=<local-address>]: Generates pages from a locally running instance of Ghost and overwrites/updates existing pages.
  • buster preview: Allows you to preview the local static site at localhost:9000.
  • buster add-domain [domain-name]: Adds CNAME file with custom domain name as required by GitHub Pages.
  • buster deploy: Pushes your changes to GitHub.

Generate Static Ghost Blog

You should create a new folder for the static version of your blog. I created one in my Documents folder, this way both my original Ghost blog and the static version of my blog reside in the same directory:

mkdir ~/Documents/ghost-buster

Make sure that Ghost is still running by going to http://127.0.0.1:2368, if it is not running then go to Ghost’s directory and: npm start.

Set up Buster:

cd ~/Documents/ghost-buster
buster setup

You will be asked to enter your GitHub repository URL, copy-and-paste it in. It should be: https://github.com/username/username.github.io, where username is your GitHub username.

Now, generate your static site:

buster generate --domain=http://127.0.0.1:2368

If you want, you can take a look at your generated site before uploading it to GitHub Pages by using: buster preview.

Go to http://127.0.0.1:9000 to view your static site.

Press Control + C to stop previewing.

Custom Domain

This step is optional, feel free to skip it.

Instead of using the default .github.io address for your blog, you can use a custom domain name for your site.

All you have to do is create a CNAME DNS record pointing your custom domain name to username.github.io.

After adding the DNS record, go back to terminal and:

buster add-domain custom.domainname.com

where custom.domainname.com is the domain name which you pointed to username.github.io.


And Finally, to push (upload) your blog to your GitHub repo:

buster deploy

You will be asked to enter your GitHub Login Credentials.

Once the upload is complete, open your web browser and go to http://username.github.io or your custom domain name (if you went that way).

Give it a couple of minutes for your blog to show up, there will be a delay this very first time. In the future, changes will show up pretty much instantly.

Making Changes to your Blog

In the Future, if you want to make any changes to your blog like adding a new post or making any changes to the source code. Then, all you have to do is:

  1. Start Ghost: npm start.
  2. Make your changes.
  3. buster generate --domain=http://127.0.0.1:2368
  4. buster deploy

Thats it!