Troubleshooting

Find solutions for common setup, upload, routing, and theme configuration issues that can appear while installing or updating your Ghost theme.

Use the same ZIP filename for each update, for example theme-name.zip. This helps Ghost keep the existing Design & branding settings for that theme.

Ghost stores Design & branding settings by uploaded archive name. If you upload theme-v1.zip and later theme-v2.zip, Ghost treats them as separate themes and the settings will not carry over.

This applies only when updating the same theme. Different themes can have different custom settings.

This usually means a previous theme used a custom routes.yaml file. Reset routes.yaml to the default Ghost routes to resolve it.

routes:
collections:
  /:
    permalink: /{slug}/
    template: index
taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

1. Go to the 'Labs' settings in the Ghost Admin to find the 'Routes' section.
2. Upload the routes.yaml file with these settings:

routes:
collections:
  /:
    permalink: /{slug}/
    filter: featured:false
    template: index
  /featured/:
    permalink: /featured/{slug}/
    filter: featured:true
    template: index
taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

The theme uses local storage to save bookmarked articles in the reader’s browser. Stored data includes the saved post reference, title, URL, and optional image needed to display the Bookmarks panel. The bookmarks feature does not transmit this stored data.

This storage is used only to provide the saved articles feature and is not used for analytics, advertising, or cross-site tracking.

Bookmarks are not synced across devices and are cleared if the visitor clears local site data or disables local storage.

For transparency, mention this local storage use in your Privacy Policy or Cookie Policy.