Hacking Ghost

How to add a custom page/component to ghost.

Hacking Ghost
Photo by Vishnu R Nair / Unsplash

It hasn't been that long since I installed ghost and already the itch to add more cool things is present. Prior, in a PHP-based version of my blog, I created a pretty nifty reading list of my online library. I wanted to bring back that to ghost, yet the annoying developers keep preaching the mantra that developing features that extend ghost means 'you wanted wordpress.. go install wordpress'.

Shut up. 🖕

Since no one online seems to care. I will post my own version modifying ghost as needed. It took less than an hour to find out where ghost kept its secrets. The source is public anyway so you can skim through it yourself. This is what I did, for now, and eventually, I will refine this as I understand it more.

Step 1

One of the secret sauces is the file


Say you want to add a route /books  to your website, you can stick in the code:

Around line 92 or so. This adds the route /books to your website, and would be accessible at https://website.com/books

The keen eyes of you will notice that I already pushed data that can be read by handlebars in the second parameter as an object. This is a nice place to add any custom data you want. Feel free to pull from any API or database. I will update this tutorial soon to include data from the ghost DB using its native CRUD system.

Step 2

Next is to add the secret handlebars source. Head over to your theme folder (I use casper):


And create the HBS file you specified above. I used books so my file should be books.hbs

Next, you can fill in this file with the default surrounding HTML. A simple example would be something like this:

Step 3

Restart your website using the ghost-cli: $ ghost restart via SSH in the folder ghost was installed.

I noticed the custom page will throw errors unless the home page is visited first. I assume this is some middleware or engine/cache issue. However, this is only for the first visit, any subsequent visit appears normal. I will try to sort this out in the coming guides, but for now, visit your home page first, and then your custom page. It should look like this:

Notice the custom data I passed in the express route above can be easily accessed by handlebars.

Those tools alone will be enough to build a very powerful ghost site.

If you have any thoughts or improvements, let me know and I can include them.

- Gib