Theme merging

You've customized your Ghost theme to make it perfect for your site. Now there's a new version available with bug fixes and features you want—but you're worried about losing your hard work.

This is one of the most common challenges theme users face. The good news? You can have both your customizations and the latest updates. Here's how.

Why updating themes breaks customizations

When you edit theme files directly and then install a new version, Ghost replaces those files entirely. Your customizations vanish because they were never separated from the original theme code.

The solution is to identify exactly what you changed, then carefully reapply those changes to the new version.

The Compare Folders method

The easiest way to see your customizations is to compare your modified theme against the original using VS Code's Compare Folders extension.

What you'll need

• VS Code (free code editor)
• Compare Folders extension (free)
• A copy of the original theme version you started with
• Your customized theme files

Step-by-step guide

1. Install the Compare Folders extension

Open VS Code, click the Extensions icon in the sidebar, and search for "Compare Folders." Install the extension by L13RARY.

2. Download the original theme

Download the exact version of the theme you initially installed. This is your baseline for comparison. If you don't remember the version number, check your theme's package.json file for clues.

3. Set up your folders

Create two folders on your computer:

• theme-original - Extract the original theme here
• theme-customized - Copy your current customized theme here

4. Compare the folders

In VS Code, right-click the theme-original folder in the sidebar and select "Compare Folders." Choose your theme-customized folder to compare against.

5. Review your changes

The extension shows you exactly which files are different and highlights the specific lines you changed. Common customization areas include:

• CSS files (colors, fonts, layouts)
• Template files (HTML structure)
• JavaScript files (functionality tweaks)

6. Install the new theme version

Upload and activate the new theme version in Ghost. Your site now runs the latest code, but your customizations are gone—temporarily.

Tip: After uploading the theme my settings in Design section were reset, what should I do? The best solution is to always use the same name e.g. theme-name.zip – that way you will not have to enter your settings again after uploading a theme.

Ghost assigns the settings in the 'Design & branding' section to the name of the uploaded archive. If you upload theme-v1.zip and theme-v2.zip – Ghost will recognize them as two different themes – so the settings will reset.

7. Test thoroughly

Check every page where you made customizations. Make sure everything works and looks correct.

Pro tip

Next time, consider using Ghost's code injection feature for CSS and JavaScript customizations instead of editing theme files. This keeps your changes separate from the theme, making updates painless.