Update April 18, 2023:
With Ghost v5, it looks like some of these instructions weren't working. I had to go back to the drawing board and it took me a good afternoon to get this running again.
Here are the key steps:
- Make sure
NPMare installed on your system.
- Make sure you are able to run Node v18.x, as that is the latest version that seems to be compatible with the Ghost GScan/Yarn/Gulp systems (more on that in a second). Node natively installs v19.x (or highest), so you need to run:
nvm install 18
nvm run 18
- Then, make sure Ghost is installed locally:
npm install ghost-cli@latest -g
ghost install local
- Install GScan, which Ghost uses for validation checking when compiling themes:
npm install -g gscan
- Install Yarn via:
npm install yarn -g
- Then add Gulp into Yarn:
yarn add gulp
That should do it. When you're in the theme folder, you can now run
yarn run gulp) to start the auto-compiling whenever you save your changes.
Troubleshooting further: sometimes, you can get an issue where a
yarn install errors out because
gscan doesn't support the current version of node. These compatability issues are super frustrating! But you can switch to a lower version with
nvm install 16 and then
nvm run 16 and try again.
Ghost theme development isn't very hard once you understand the basic loops and handlebars code. In fact, changing a few
partials and a
CSS file and then saving things as a .zip file is enough generate a new fully functioning theme! (I've done it myself when I modified the Ease theme to create Easey and again into Cleanimalistic.
But when I started fooling around with some of Ghost's native themes, I ran into a weird problem. My CSS wasn't updating.
Was it my browser? No, I tried in incognito. Was it my server? No, I restarted by Ghost and Apache multiple times.
Turns out some Ghost themes compile their CSS into a single minified CSS file. I've come across SCSS before and know that behavior existed, but I didn't realize that Ghost uses
gulp (not SCSS) to compile its themes.
gulp is a task runner built on
npm, used for automation of time-consuming and repetitive tasks involved in web development like minification, concatenation, cache busting, unit testing, linting, optimization, and more.
In certain Ghost themes, gulp is uses to combine partial CSS files into a unified, minified "Built" file. (It's also used to compile other things, but that's outside of scope here). If you're running
gulp in development, it will ensure that your theme is copiling and updating in real time. You also use it to compile and package up your code when you're ready to deploy it to your site.
So if you're working with a Ghost theme and your CSS doesn't seem to reflect the changes you've been making, here's what you can do:
Firstly, make sure you have
npm installed first: https://www.npmjs.com/get-npm
Once that is installed, enter into your theme directory via the terminal (
cd Documents/GitHub/ghost-rdc-blog/ for me) and install both
npm install yarn -g npm install gulp -g
-g command is to install the package globally.
Once you have that, run
gulp run. Now when you start working with changes on your system, you window should now look something like this:
Great! This means your code is recompiling as you make changes! This is good! (It also appends a unique variable to access your CSS and JS files to break through local caches when you make changes).
Next, you're going to want to do
npm run zip to generate a compiled "Distribution-ready" of your theme:
Once the zip function finishes (shouldn't take more than a few seconds), your final .zipped version of the theme can be found in the
Simply upload that to your site and you should be good!
For further reference, I found these docs below helpful. They didn't get me to 100%, but set me on the right path: