Skip to main content

Tags management in Docusaurus

Automate Docusaurus tag management with this Python script. Clean up duplicates, fix casing, and merge tags safely across hundreds of Markdown files via Docker.

· 4 min read
View raw
Christophe
Markdown, WSL and Docker lover ~ Insatiable curious.
Cet article existe aussi en français — lire la version française.

Tags management in Docusaurus

⚡
TL;DR

This article introduces a custom Python script designed to automate the cleanup and management of inconsistent tags within a Docusaurus blog. The tool runs in a Docker container to list, rename, and delete tags while providing smart suggestions for merging duplicates or fixing case variations. It also discusses using Docusaurus's native configuration options to enforce stricter tag usage policies moving forward.

More than 200 blog posts later, my Docusaurus site has accumulated a bit of tag chaos. Too many similar tags, inconsistent capitalization, singular vs plural forms... Tags with just one or two posts. And so on.

In this post, I'll share a Python script I wrote to automate tag management like removing some tags, merging others, and cleaning up inconsistencies.

It's quite impossible to do by hand when you have hundreds of Markdown files. Plus, doing it manually risks breaking the YAML frontmatter formatting.

Seeing the Suggestions​

One command lists every tag and flags the likely duplicates:

>user@machine: ~/yourproject

List of tags

The Solution: A Smart Tag Manager​

I wanted a tool that could do three things:

  1. List all tags by frequency.
  2. Suggest optimizations (finding duplicates or singular/plural variations).
  3. Rename or Delete tags safely.

Smart Suggestions​

The coolest part of the script is the "Optimization Suggestions". It compares every tag against every other tag to find potential duplicates.

It looks for:

  • Case variations: GitHub vs github.
  • Plurals: snippet vs snippets.
  • Substrings: visual studio code vs vscode.

This helps me spot the mess I didn't even know I had.

How to Run It (Docker-First)​

As always, I don't want to pollute my host machine with Python dependencies. I run this script using Docker — exactly like the image checker described in Running some checks on your Docusaurus images.

I have a Makefile target set up, but essentially, it runs a command like this:

>user@machine: ~/yourproject

But, for sure, that command is quite complex to remember, so I use a Makefile target instead:

The Script​

Here is the full Python script. It uses argparse to handle command-line arguments and python-frontmatter to parse the files.

More Examples​

Renaming a tag:

If, by looking at the list of tags, I see I have a snippets tag and a snippet one, I'll merge them like this:

>user@machine: ~/yourproject

Deleting a tag:

I can also find that a specific tag doesn't add any value so, to remove it, I'll run something like this:

>user@machine: ~/yourproject
Bonus - The tags.yml file

Natively, Docusaurus allows you to create a special file called blog/tags.yml.

Here is the one I'm using:

With such file, you can then configure your docusaurus.config.js file and set the onInlineTags attribute to warn or throw.

Need more info, read the Tags File official documentation.

Conclusion​

Keeping a blog organized is a continuous process. With this script, I can quickly audit my tags and ensure that Docusaurus doesn't become docusaurus or DocuSaurus over time.

Feel free to grab the script and adapt it to your own static site generator!


Was this article helpful?
Did you try the steps in this article?
🦋 Join the conversation on BlueskyRequires a free Bluesky account to like, repost or comment. This block talks to Bluesky's public API directly from your browser (no cookies, no sign-in) — that means your IP address reaches Bluesky's servers just by this section loading.

Loading comments…