Tag Wrangler

Merging duplicate tags by dragging them onto the one to keep, the behaviour settings that decide how posts are rewritten, previewing the blast radius, undoing a run, and deleting unused tags.

Got too many tags?

It happens every few months. Some site (usually migrating from WordPress) with 20 tags on every post, many of those tags used once on the whole site. It's a mess. Ghost has no tag merge, so near-duplicates accumulate: Local News, local-news, Local. Tag Wrangler lets you merge and tidy up your tags with a friendly GUI: pick the tag to keep, drag the others onto it, preview what changes, and apply. Every post and page carrying the dropped tags gets retagged.

⚠️ With great power comes great responsibility. Back up your content before you use bulk tools. In Ghost, go to Settings → Import/Export → Export and choose the content export.

Get it running

Back up your content, as above. Nothing here is reversible except the single most recent run.
Pick the tag you're keeping and make it a target. Search the tag list, select the one that should survive — usually the one already in heaviest use — and press Make selected tag a target. 4:24
Drag the duplicates onto it. Drop local-news and Local onto Local News. Nothing has happened to your site yet — the plan only exists on this page until you apply it, so build up as many of these as you want to fix in one go. 4:31
Set the behaviour. Replace for a merge, a position, and — for a real cleanup — Delete the replaced tags afterwards. Leave the empty tags behind and your writers will keep applying them; you'll be back here in a year. 4:42
Preview changes, and read the primary-tag line. It tells you how many items will be retagged and how many will end up with a different primary tag — the one that matters, because some sites put the primary tag in their post URLs. 6:11
Apply, then check History. The run goes in batches with progress on screen. When it's done, the History tab records what you did — and offers the one undo you get. 7:06

Everything below is reference, ending with what to check when a merge doesn't look right.

The video introduces Tag Wrangler and its sibling, Bulk Actions; Tag Wrangler starts at 3:28.

Targets and dropzones

The Consolidate tab lists every tag on your site with its post count. Select the tag you want to keep and press Make selected tag a target, or type a name into Add a new tag to Ghost to merge into a tag that doesn't exist yet. Each target gets a dropzone; drag the tags that should fold into it onto the zone. A tag can be dropped onto one target only, and a chip can be dragged from one dropzone to another. Remove target dissolves a zone and frees its tags.

Each dropzone also has Also make [target] the primary tag on every post and page that already has it. Tick it and the target moves to the first position on those items, which is what Ghost treats as the primary tag. A dropzone with that ticked and nothing dropped in it is allowed, and does only that. Internal tags (the ones starting with #) can never be a primary tag, so the box does nothing for them.

Behaviour

One setting at the top of the page applies to every dropzone in the run:

Mode. Replace takes the dropped tags off each post and puts the target on instead. Add keeps the dropped tags and adds the target alongside them.
Position. Where the target lands in the post's tag list: First (it becomes the primary tag), Same position as the tag it replaces (Replace mode only), or Last.
Delete the replaced tags afterwards (Replace mode only) removes the dropped tags from Ghost once nothing carries them.

Preview, apply, undo

Preview changes counts what the run would touch: published, draft, scheduled and sent posts, and pages. It also says how many items would get a different primary tag, which can change URLs under some routing configurations, so read that line before going on. Apply starts the run in the background; the page shows its progress, and you can leave and come back. Each post is re-read just before it's written, so an edit someone makes in Ghost while the run is going is skipped rather than overwritten.

The History tab lists past runs. The most recent completed run can be undone, which puts every post's tags back as they were. Tags deleted by "delete afterwards" are recreated on undo.

Delete unused tags

Delete unused tags finds every tag on zero posts and zero pages and lists them for you to confirm. Deleting is permanent and can't be undone, and the server checks each tag is still unused at the moment you confirm.

Do it as part of a tidy-up rather than skipping it. A tag left on your site with nothing on it still shows up when a writer starts typing, so it gets applied again, and the mess you just cleaned up rebuilds itself.

A deleted tag's page returns a 404. Anyone following an old link to /tag/local-news/, and any search engine holding that URL, lands on nothing. If those pages had traffic worth keeping, note the slugs before you delete and add redirects to the surviving tag in Ghost's redirects file. Nothing here writes them for you.

When a merge doesn't look right

The tag counts haven't changed

Give it a moment and reload. The tag list is cached, so it can lag behind a run that has already finished — particularly on a big site, where the run itself takes a while.

Preview says fewer items than I expected

Preview counts what actually carries the dropped tags, across published, draft, scheduled and sent posts, and pages. A tag whose Ghost count looks higher is usually counted differently there, or some of those items already carry the target too, so nothing needs to change on them.

My post URLs changed

That's the primary tag. Ghost treats the first tag on a post as its primary tag, and some sites build post URLs from it, so a merge that moves a different tag into first position rewrites those URLs. The preview's "different primary tag" line is the warning for exactly this — and if you've already applied, the undo puts them back.

I need to undo something older than the last run

You can't. Undo covers the most recent completed run only. Going further back means recovering from the export you took first — and that's worth doing with help rather than by re-importing the file, which would bring back everything in it as duplicates. Email me and we'll work out what actually needs restoring.

Someone edited a post while the run was going

It was skipped, not overwritten. Each item is re-read immediately before it's written, and one that changed underneath is left alone. Re-run the same plan to catch it.