Start a conversation

Migrating to Ghost 1.0

Ghost 1.0 is a major upgrade, with breaking changes that could impact the display of your publication. Before following the upgrade process below, please review all potentially 'breaking changes' that should be addressed prior to upgrading your site.

Public API Breaking Changes

If you are using the Public API from an external site, you will need to update your code snippet for Ghost 1.0.0, so that the ghost-url.min.js references the new location and file name. 

It's previous location was /shared/ghost-url.min.js , however it has been has been moved and renamed to /public/ghost-sdk.min.js, as shown below:

<script type="text/javascript" 
src=""> </script>
<script type="text/javascript">
  clientId: "ghost-frontend",
  clientSecret: "<letters-and-numbers>"

 You can read the full API migration guide for more details. 

Markdown Breaking Changes

Pre-1.0 versions of Ghost used a Markdown parser that allowed certain Markdown to be written that wasn't "valid" according to any agreed Markdown specification, however from 1.0 onwards Ghost is using a fully CommonMark compliant parser/renderer. Unfortunately there were a few cases of invalid Markdown that became fairly common to use in Ghost 0.x versions, but will no longer work after upgrading to 1.0. 

All documented markdown breaking changes can be view here. Please read through the changes thoroughly and correct any content formatting before upgrading to Ghost 1.x.

If you have a markdown problem that can't be resolved by following the above guide, swing by our forum to get help. We'll update the Markdown changes list as we become aware of any other common differences between 0.x and 1.x Markdown support.

Theme Breaking Changing

There are breaking changes in the theme API between Ghost LTS and 1.0.0, that means your theme may need to be updated before you are able to migrate over to Ghost 1.0

The best way to check for potential breaking changes is by using our tool, gscan. If you navigate to and download your current active theme, you can then upload it to to get a report on any changes that need to be made.

There's a full guide to migrating themes to Ghost 1.0.0 in our theme docs.

Upgrading to Ghost 1.0

To upgrade to the latest version of Ghost, please follow the steps below:

  1. Log into your account.
  2. From your publication list on, click Upgrade Now on the publication you wish to upgrade.
  3. On the publication settings screen, click the green Start Upgrade button to begin the upgrade.

  4. During the upgrade process, we will check your theme for compatibility with the latest version of Ghost. If there are no issues to resolve with your theme, the upgrade will continue to process until finished and your publication will be on the latest version of Ghost.

    If your theme is not compatible with Ghost 1.0, you will see the Theme Compatibility Errors list, indicating what errors will need to be corrected in your theme before you can complete your upgrade to Ghost 1.0.
    Once the changes to your theme have been made, you will need to upload the theme to your publication, making sure to set the compatible theme as the active theme before starting your upgrade again from

If you are having trouble with your upgrade, or have questions regarding theme compatibility, please contact [email protected] for help.

Choose files or drag and drop files
Was this article helpful?
  1. Sarah Frantz

  2. Posted
  3. Updated