I’m on Ghost(Pro) and about to [takes deep breath] dig into modifying/customizing a theme. What’s a recommended workflow for working on a new or modified theme – ideally with existing site data – before going live with it? Grateful for any suggestions/step-by-step.
I recommend developing locally. While you /can/ repeatedly load your theme onto Ghost Pro (and if you’re going that route, you want the github action as it makes that much faster), it’s much nicer to test locally, where you can see the errors and the feedback loop is near-instant. (Especially if you start ghost with ghost run -D, which provides extensively verbose errors to the terminal.)
Here are local install directions:
I strongly recommend that if you’re on Windows, you 100% ignore the Windows directions and instead set up WSL2 with Ubuntu 22. It’ll take you slightly longer (because you’ll be waiting on the Ubuntu install), but then you’ll be running Linux, and most people run on Linux, so you’ll get better support and are less likely to hit a Windows-only bug.
There’s theme-editing documentation is here: Ghost Handlebars Themes - Building a custom Ghost theme - Docs . Tip: While Ghost themes use handlebars, they use a Ghost-specific dialect of handlebars. Generic handlebars documentation isn’t going to be very helpful. (And ChatGPT is likely to give you code with helpers that don’t actually exist.) Use the Ghost docs instead: Ghost Handlebars Themes - Functional Helpers
There are a bunch of good tutorials on doing theme development here: Tutorials
New themes: There’s a Ghost Starter theme available (from @TryGhost) on Github. Starting from that or another free theme is a good jumping-off point for whatever you’re building.
In terms of site data: I wrote a thing here that walks you through what to move and how:
Tip: When you’re done editing your theme, ONLY move the theme file back to the live site. Don’t import any of your exports above, or you’ll get duplicate posts and a giant mess! :) (Ask me how I know. Only made that mistake once.)
Newbie mistakes to avoid (or at least recognize when you make them):
- Don’t forget to restart Ghost after adding new .hbs files.
- Nearly all themes have a step that compiles/builds/minifies the css and/or js. Failure to run that step will cause you to wonder why none of your changes are taking effect.
1 Like
This is great, @Cathy_Sarisky. Thanks for all the details.
A noob question on implementation: Say I have a new theme to install on the live site, and I do, and quickly discover it clearly needs more work. Can I just re-install the prior theme, no harm/no foul? Guess I’m wondering if anything is set/reset by loading a new (or old) theme that would then require some fixes.
1 Like
If you upload a theme .zip file with a different name, the old version of the theme will be there, and you can quickly (re-)activate it.
If you upload the theme with the same name, then it’ll overwrite the old version, and so you’d need to upload a corrected (or original!) copy of the theme.
Why would you upload with the same name? Tradeoffs. If you upload with the same name, then all the theme settings are retained. If you upload with a new name, then all the theme-specific settings (everything in settings > design except those in the brand tab) gets reset to defaults, which means a minute or three of resetting all the theme’s custom settings to the desired values.
Personally, I /generally/ choose to overwrite, but I grab a copy of the theme right before doing my upload, in case I need to quickly undo a mistaken upload. If I think there’s a chance my client is going to want to revert while I’m asleep, then instead I copy all the settings over.
It would be super handy to have a tool that copied theme settings from one copy of the theme to another (as much as those settings match, anyway). Someone should write one…
@Cathy_Sarisky Perfect, that’s exactly what I needed to know, re what needs to be reset in various scenarios. Thanks again.
1 Like