Upgrading Legacy Ghost Themes to 6.x: A Practical GScan Checklist
Legacy Ghost themes need more than a version bump. A GScan-driven checklist for Ghost 6—helpers, cards, members, AMP removal, and deploy verification.
Ghost 6 is not a repaint. Themes that passed GScan on 4.x or 5.x may still fail on Node 22, Lexical card markup, locale helper changes, and AMP removal. Before you zip and upload, run GScan and walk this checklist.
Step 0: Baseline with GScan
From the theme root, run gscan content/themes/your-theme. Fix errors before deploy; treat warnings as a prioritized backlog. Update package.json with "engines": { "ghost": ">=6.0.0" }.
Checklist: package and structure
package.jsonincludes validname,version, andengines.ghost- Required templates:
index.hbs,post.hbs default.hbsincludes{{ghost_head}},{{ghost_foot}},{{body_class}},{{{body}}}- Remove AMP templates — deprecated in Ghost 6
routes.yamlvalidates if present
Checklist: Ghost 6 breaking helper changes
Replace @lang with @site.locale. Use {{t "key"}} with locale files. Adopt {{social_url}} helper patterns. Delete AMP-specific partials.
Checklist: members and Portal
If @site.members_enabled, verify Portal triggers, paid content states, @member gates, and no duplicate Stripe embeds. See Portal Explained.
Checklist: Lexical cards and content
CSS must target current kg-card classes including width variants. Preview real admin posts—not lorem templates.
Checklist: images and performance
Use {{img_url}} with declared sizes in package.json. No hard-coded external image URLs in templates.
Checklist: pages and custom templates
Respect @page.show_title_and_feature_image. Verify custom-*.hbs mappings and error templates.
Deploy verification
After GScan passes: activate on staging, browse all template types, test Portal on mobile, verify newsletter links, run Lighthouse—then promote to production.
When to rebuild vs patch
Patch small themes with localized GScan fixes. Rebuild when carrying Bootstrap-era markup, AMP forks, or pre-2.0 patterns—the refactor cost exceeds a clean Ghost 6 base.
For platform context, see the Ghost 6.0 release guide and routes.yaml magazine patterns.
Discussion