How to Update Your Ghost Theme When We Release New Versions

Ghost CMS is constantly developed, new features being added regularly. To keep up with these changes we maintain and update our themes to support these new features, fix bugs or simply update the theme dependencies and plugins that are used.

When we release a new update for a theme, you will get an email with useful information about the update, like is new in this version (features added, bugs fixed..) as well as a list of files that were changed in this version (new files, updated files, deleted files). This information can also be found in each theme's changelog.

Now that you have this information, let's see how the process of updating your Ghost theme would look like in general:

• Download and backup the current theme
• Update the theme
• Build the assets
• Zip and Upload the new version

Download and backup the current theme

First of all download the theme zip file from your Ghost Admin area.

Go to Settings → Design → Change Theme > Advanced.

Press Download , this will prompt you to save the theme zip file.

Generally it's a good idea to keep a backup of this file, just in case something goes wrong during the update.

Next, unzip the downloaded file so you will be able to work within the directory.

Download the latest version of the theme and also unzip this one in a separate directory.

Update the theme

Now that you have a backup and unzipped the theme (current and new version), let's start with the update process.

The updates are structured in the following types of changes:

• new files

  • For new files what you have to do is copy the file from the latest version of the theme into the same directory of the current version you downloaded from your Ghost Admin.

• deleted files

  • These files can be deleted from your current version.

• changed files

  • This part will depend whether you have customized or changed that particular file. If you didn't change it during your customizing than you can safely copy and replace the file with the new version.
  • If you changed the file then you would have to integrate the changes into the latest version and then copy and replace the file in your current theme.
  • Do the same thing for all the changed files.

When you are done with all the files the update process is done.

Build the assets

Our themes have some build processes to create minified and optimized js and css bundles that are used by the theme (for better performance).

In case you did some customization in the js and/or css files, then you should check out the Theme Development section in the documentation of the theme to see how the assets should be built.

In case you didn't have any customizations in your css and js files than you can skip this part.

Zip and upload the new version

Once all the steps above are done, you can zip the theme directory and upload this in the Ghost admin area. Settings → Theme.

Press Upload a theme and in case you get a prompt, click Overwrite.

That's it, if you go to your website the theme should be active and you can check if everything is working as expected.

In case you encounter any issue you can try the following:

• check the changelog if there was any special step mentioned there
• try to Activate the theme again
• upload the backup zip file (old version) to check whether the problem is with updated version
• restart Ghost

Also, if you are looking to improve the deployment process you can check out this article about ghost theme deployment using Github Actions.