Migrating to 1.0.0

A guide to getting your site updated to Ghost 1.0.0

Ghost 1.0.0 is a major upgrade, with breaking changes and no automatic migration path. Although this migration is going to be more painful than usual, we hope you'll find it's worth it! If you install using Ghost CLI then from 1.0.0 onwards, upgrades are going to be as simple as ghost update 🎉

To migrate to 1.0.0 you will need to handle breaking changes in the Theme API, and in the Public API if you make use of it.

Unlike previous upgrades you will be creating a brand new install and importing your JSON export, instead of migrating the old one. As with previous upgrades, we very strongly recommend backing up before you begin.

Only really this time. Please back up. Please.


Here's a basic breakdown of the migration steps:

  1. Prepare your theme in advance
  2. Backup your content using the JSON exporter
  3. Create a brand new Ghost v1.0.0 site following our install guide
  4. Use Ghost v1.0.0 Importer to import existing content
  5. Copy your images to your new site.
  6. Upload your theme - your theme will not be uploaded from the importer
  7. Update external sites using Public API - if you fetch data via the Public API, you'll need to update the credentials on your external sites

Public API breaking changes

There are 2 issues which impact the Public API when accessed from external sites:

  • Ghost 0.11.x LTS exports do not include clients & trusted domains and therefore will not be imported to your new site.
  • The /shared/ghost-url.min.js util has been moved and renamed to /public/ghost-sdk.min.js

Read the API migration guide for more details of how to fix this.

Markdown breaking changes

Automatic footnote numbering is no longer supported in 1.0. If you have [^n] style footnotes in any of your posts you will need to manually update them to be fully identified with a number [^1] or a label [^my-footnote].

Please see our Markdown Guide for further information on supported footnote syntax.


Markdown inside of HTML tags must be separated by blank lines. Eg.

<figure>
![](https://example.com/image.png)
</figure>

should be written as:

<figure>

![](https://example.com/image.png)

</figure>

Spaces in link URLs are not supported and should be urlencoded. Eg:

[my file](https://mysite.com/my file.pdf)

should be written as:

[my file](https://mysite.com/my%20file.pdf)

0. Prepare your theme

There are breaking changes in the theme API between Ghost LTS and 1.0.0, that mean your theme may need to be updated before you are able to update.

The best way to check this is with gscan. If you navigate to yourdomain.com/ghost/settings/ and download your current active theme, you can then upload it to https://gscan.ghost.org to get a report on any changes that need to be made.

There's a full guide to migrating themes over in the theme docs.

1. Backup your content

Copying your SQLite3 DB will not work!

When migrating to Ghost 1.0, you will need a JSON export file. There is no way to migrate to 1.0.0 using only an SQLite3 DB file.

For general backups, it is possible to keep a copy of your sqlite database file although you should always stop Ghost before copying the file to prevent file corruption.

When backing up a Ghost site, there are 2 main things that need to be done. 1. grab an export from labs, and 2. ensure you have a backup of your content folder.

JSON export

To get an export, in your existing Ghost site, navigate to yourdomain.com/ghost/settings/labs/ (the settings > labs page in Ghost-Admin) and click on the Export button. It should look something like this:

lts labs page

lts labs page

This will download your JSON export file that you need later.

Content folder backup

All user-provided data, such as images and themes, live in the /content/ folder. It's always a good idea to make a quick copy of these files so you've got access. Easiest way to do this is to run cp -r content /tmp/content-backup on your server.

You can also download your active theme from the labs page.

2. Create a new Ghost 1.0.0 install

Next you'll need a clean install of Ghost 1.0.0.

Check out our install guide to create a new production site using Ghost CLI.

3. Use the Ghost 1.0.0 importer

All user accounts are locked on import

As has always been the case, the Ghost importer does not import user passwords or tokens. All user accounts (except the one used to do the import) are locked on import. Users will need to use the password reset mechanism to regain access.

On your new site import navigate to yourblogdomain.com/ghost/#/settings/labs (the settings>labs page in Ghost-Admin)

Click Choose file and select the JSON export file created in [step 1] then click on the Import button.

v1.0.0 Labs page

v1.0.0 Labs page

Note:

The importer will not import themes from LTS blogs

You should see a warning that your theme has not been imported, this is expected and you can continue on to step 4.

If see other warnings or errors, you may need to troubleshoot your Ghost Import.

4. Copy your images

Your content directory functions the same, and exists in the same place in 1.0 as in previous Ghost versions.

You need to copy/move your images from your existing directory <old-ghost-dir>/content/images to the new blog directory <new-ghost-dir>/content/images.

After copying any files into the /content/ folder, you must make sure they belong to the Ghost user. This can be done by running sudo chown -R ghost:ghost content inside of your Ghost install.

5 Upload your theme

Navigate to yourblogdomain.com/ghost/#/settings/design (the Settings>Design page in Ghost Admin) then click Upload a Theme button and follow on-screen instructions.

Upload a theme

Upload a theme

You can also copy the theme into <new-ghost-dir>/content/themes, but you must make sure the folder is owned by the ghost user and will need to run ghost restart to get Ghost to see it.

Posts per page setting:

The posts per page setting is now controlled by your theme, and this will default to 5 posts if not set.

Favicon.ico

Ghost now uses the "Publication Icon" in settings to output a favicon automatically. Please upload a 60px by 60px icon in /settings/general/ - this will be used to output an icon, including a favicon.ico, anywhere that icons are needed.

6. Update external sites using Public API

If you have external sites which are using the Public API to pull data from Ghost, you'll need to make some updates to ensure this stays working.

See the API migration guide for more information.

Migrating to 1.0.0

A guide to getting your site updated to Ghost 1.0.0