Get a Ghost blog up and running with Github Pages

After crafting a brand-new portfolio, I decided that I needed a dedicated space to write. I wanted to create posts with minimal effort and spend more time writing than formatting. Wordpress went way beyond my needs, and Medium seemed like a neat way to go, but I wanted the freedom that comes with self-hosting. That led me to Ghost, a super simple blogging platform that lets me craft posts in Markdown. Couple Ghost with Buster, a static site generator, and Github Pages, I had a free path towards my own self-hosted blog!

Buster is essentially a Python hack, but it works, and it gets the job done. Unfortunately, the documentation is sparse, and I ran into bugs and issues while trying to install. For my own future reference and to the benefit of anyone else interested in hosting their own Ghost blog on Github Pages, here are the steps I took:

Note: I am working off a Mac and I will assume you have Node.js and wget installed (I used Homebrew to get everything I needed).

Install Ghost locally

Create a folder inside any directory you’d like. Download the latest version of Ghost, and unzip the contents into that folder. You could clone Ghost from Github into the folder, but I ended up facing access issues I could never resolve. This is faster and cleaner.

When that's done, open up your terminal and:

  1. Run npm install
  2. Run npm start
  3. Log into your Ghost account, set up your blog, and perhaps make a test post at http://127.0.0.1:2368/ghost

*You can shut down Ghost when you’re done with Ctrl+C, but you’ll need it running later. So either open a new terminal window/tab to continue running other commands, or just shut down Ghost for the moment.

Setup Github Pages

Go to Github and create a new public repo. If you'd like to create a a "user page", go ahead and name the repo USERNAME.github.io. If you are already using your user page to host something else, you have to create a “project page”. Go ahead and name the repo anything you want. I simply called mine "blog".

Do NOT initiate the repo with a README file! Leave it as a blank repository. In the next steps, Buster will go through the trouble of creating a gh-pages branch so you can actually see your blog. No sweat.

Generate and Deploy the Static Pages

This is when you should double check that Ghost is running locally on another tab in the terminal. If not, you need to fire it up again with npm start.

Run pip install buster
Run buster setup gh-repo=[repo url]. I suggest using the HTTPS clone url (e.g. https://github.com/USERNAME/REPO.git)
Run buster generate
Run buster deploy

After deploying, Buster should congratulate you with “Good Job! Deployed to Github Pages.” You can navigate to username.github.io or username.github.io/repo to see your brand new blog!

Easy as pie!

When making updates to your blog locally, make sure Ghost is running before you push all changes to Github using buster generate, then buster deploy. The simplest blogging solution ever!

Extra Notes:

As mentioned in a development issue described here, buster generate has issues when the local git repository is in a folder whose file path has spaces in it. For example I tried running Buster in a directory that looked like /Documents/Code Projects/blog. The space in “Code Projects” was apparently an issue, so I started over in a new spaceless directory (/Documents/SPACELESS/blog), and everything was fine!

Custom themes can be added to Ghost by adding the theme folder to the content/themes subfolder in the Ghost installation. Restart Ghost and make the changes under your blog settings.

Vanessa Ogbuehi

I'm a creative person working in theatre and web development. Trying to satisfy my curiosity and insatiable desire to create new things

comments powered by Disqus