Setting up a Ghost Blog with Github Pages

Github Pages is a static site host on Github for hosting simple blogs for developers or landing pages for their open-source projects. Ghost is “just a blogging platform” that’s open source and is known for being extremely easy to use while also being beautiful out-of-the-box. It’s very similar to Jekyll – a Ruby-based static site generator that Github Pages uses behind the scenes – except that Ghost is written in JavaScript and was started as a Kickstarter project.

This blog post (built with Ghost and hosted on my Github Pages blog) will guide you through the process of publishing your own personal blog hosted by Github for free! The general idea behind this process is to let Buster generate a static HTML and CSS version of your locally-running Ghost blog server, publish the files to a Github repo, and then 1-20 minutes later you enjoy your blog, which pulls the pages from that repo and serves them on the default URL of [your-github-username].github.io!

Install Dependencies, buster and Ghost

First, you must create a folder to hold your Ghost files and static files. I chose to do this in my Dropbox folder, as I’ll explain later.

$ mkdir ~/Dropbox/blog

Then you’ll need to make sure you have both Node.js and Python installed to run the Ghost server and Buster. Apple Macs should have Python installed by default and I prefer using nvm to install Node.js and npm. If you need to install Node.js and npm, I highly recommend following this simple guide which uses homebrew (an OS X package manager) to install nvm, which will then let you manage multiple versions of Node.js and npm very easily.

We’ll also need a tool called wget that’s used to retrieve content from web servers, and we’ll also install it using homebrew:

$ brew update
$ brew install wget

Next, we’ll have to install Buster and Ghost; if you have pip (a Python package manager), installing Buster is as simple as:

# go to your blog's directory
$ cd ~/Dropbox/blog

# if you don't have already have pip
$ sudo easy_install pip

$ sudo pip install buster

while this is the easiest way I know of to install and start your local Ghost server:

$ wget https://ghost.org/zip/ghost-0.7.0.zip
$ unzip ghost-0.7.0.zip -d ghost
$ cd ghost
$ npm install --production
$ npm start

npm start starts the Node.js server that will serve up the admin interface for your blog at http://localhost:2368/ghost. This is where you’ll create an admin account for managing your local blog posts, settings and themes and also where you’ll create and edit your blog posts using Ghost’s fancy side-by-side Markdown editor.

Generating the static files for your blog’s repo

The next thing you’ll want to do is create a repo for your static blog. On Github, create a new repo whose name is [your-username].github.io. The repo’s name must be [your-username].github.io, otherwise Github won’t know to create a site at that URL from that repo.

Once it’s been created, lets start our Ghost server, create a new tab in our terminal and use buster to create our blog’s repo and its static files:

# (in a new tab) get back to the blog folder
$ cd ~/Dropbox/blog
$ buster setup --gh-repo=\
"https://github.com/<username>/<username>.github.io.git"
$ buster generate
$ buster deploy

This will create a local repo in the folder named static who’s remote is the URL to the Github repo you just created. buster generate will create all of the appropriate directories, HTML pages and links for your entire Ghost blog within that folder. The last command, buster deploy, adds, commits and pushes the changes you generated up to your blog’s repo. And that’s it! Github Pages can take as much as 20 minutes to update, but it often happens much sooner.

Every time you need make a change to your blog, whether by changing a theme or adding/editing a post, just run npm start within the blog/ghost/ folder and call buster generate from your blog folder to recreate the appropriate static files. All you have to do now to re-deploy your the latest version of your blog is buster deploy!

This is why I put blog in my Dropbox folder – edits can be made within the Ghost side-by-side Markdown editor on my main computer and will always be backed up without having to commit them to my blog’s repo, and if I happen to be on my tablet or phone, I can just edit the raw Markdown.

Once it’s been deployed and you’re done making changes to your blog, hit Ctrl-C from within the Ghost server tab to shut down the server.

And that’s it! You can check out my Github Pages-hosted Ghost blog at http://blog.sunnyg.io. If you have any questions, feel free to reach out to me and thanks for reading!