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:
- 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
pip install buster
buster setup gh-repo=[repo url]. I suggest using the HTTPS clone url (e.g.
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!
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.