Safely Build on a Ghost Theme

Safely Build on a Ghost Theme

This blog runs on the Ghost platform, and I was mildly surprised when I ran a ghost update the other day and suddenly my custom themes and scripts were just gone! Luckily I use DigitalOcean with backups enabled, and I had a backup from just a couple days before. I rolled back, verified my styles and customizations were present, then ran ghost update again. Wiped out.

In retrospect, this makes sense. There are going to be updates to Casper, the default Ghost theme, and how should they reconcile that with any local changes I've made? They can't reasonably, so they just overwrite it. WordPress had the concept of child themes, which allowed for extending a base theme, so I attempted to do something similar with Ghost.

If you find yourself wanting to use most of the Casper (or any other) theme, but with some customizations (and you don't want to shove them all into the "Code injection" tab in the ghost admin screen), then you may want to do what I did.

Fork the theme in GitHub and clone it locally

Fork the theme (i.e. Casper) in GitHub and then clone it locally:

git clone https://github.com/YOUR-USERNAME/YOUR-FORKED-REPO.git

Rename the directory on your local machine so it's different than the default theme name - something like Casper-YOUR-USERNAME. This is necessary when uploading the child theme later - the name cannot be the same as the default.

Modify it to your liking

Make any changes you'd like to the theme. I made small tweaks to add more social icons and whitespace, change the blockquote style, use Prism.js for code styling, etc.

Package and upload it

Compress the local directory so you end up with a Casper-YOUR-USERNAME.zip file, and then use the Design tab under settings in the Ghost admin to upload your new theme. Activate it (it should prompt you). Restart Ghost using ghost restart if you don't see the changes applied (but they should be).

It's worth noting that there's instructions for automating this process too, where pushing changes to a custom theme in GitHub will cause it to be automatically deployed to a working Ghost blog. Very convenient!

Deploy Ghost Theme - GitHub Marketplace
Build & deploy a theme to your Ghost site

Fetch latest official changes, periodically

To avoid missing out on future updates to the default Casper theme, keep your fork up to date (don't forget to commit your changes first).

cd into/cloned/fork-repo
git remote add upstream git://github.com/ORIGINAL-DEV-USERNAME/REPO-YOU-FORKED-FROM.git
git fetch upstream
git pull upstream master
git push

If you're a fan of git aliases, after you've run the above once you could add something like this to your .gitconfig file:

updatecasper = !cd your/casper/location && git fetch upstream && git pull upstream master && git push

NOTE:

This method of updating my local fork worked perfectly fine for me, but you may also want to checkout the official doc on Syncing a fork which suggests a git merge instead of a git pull. There's also a comment under the gist I linked to above, that suggests a way to keep forks up-to-date all through GitHub.