building with ghost

GCTools update: clean up canonical URLs

Jon Hickman

Jun 6, 2026 • 1 min read

I added a new feature to GCTools last month to help folks update canonical URLs across their site.

⁉️

GC what now? GCTools is a a collection of command line utilities for working on content in Ghost. It's particularly useful for folks who are migrating to Ghost or doing a major refactor of a Ghost site. It's essentially a Swiss Army knife for making bulk changes to posts and pages.

set-canonical-url is useful for sites migrating away from a previous platform (clear stale canonical URLs imported from elsewhere) or rewriting canonical targets to a new domain after a migration.

Ghost sets the post's own slug as the canonical URL by default. Custom canonical URLs can also be added in post settings. Posts with custom canonicals are excluded from the automatically generated sitemap. A quirk to this: if someone adds the post's own URL as a custom canonical, this is understood to be a custom canonical and the site is removed from the sitemap. If a migration explicitly adds custom canonicals that refer to the current post, the migrated posts will never be in the sitemap, so quickly stripping custom canonicals is helpful.

The default behaviour of set-canonical-url is to set all custom canonicals to null. The tool also allows for new canonicals to be set by applying a new domain to each post's slug e.g. https://example.com/topic/{slug}/ — this is useful if your Ghost site is a mirror of content already available at another domain.

set-canonical-url supports standard GCTools filtering, so you can target posts by author, date, and tag. It offers a dry run test and it is enabled in GCTools interactive mode.