jekyll-taxonomy-redirects

RubyGems listing

Generate legacy taxonomy redirects for Jekyll sites. Handy when migrating from WordPress (or any site) where you used paths like /category/:slug/ and /tags/:slug/, but your new site uses /venues/:slug/ and /acts/:slug/ (or any other mapping).

The plugin emits tiny, portable HTML redirect stubs at build time. It works with GitHub Pages when you build in CI (Actions) and deploy _site/.

Features

Generate redirects for category and tag taxonomies (slugs from your content)
Configurable from → to mappings (e.g. /category → /venues)
Optional root redirects (e.g. /category/ → /venues/)
Portable HTML stubs using <meta refresh> + location.replace()
Optional <link rel="canonical"> for crawlers
Works alongside jekyll-archives and jekyll-redirect-from

Installation

Add the gem to your site’s Gemfile:

# Gemfile
source "https://rubygems.org"

group :jekyll_plugins do
  gem "jekyll-taxonomy-redirects", "~> 0.1"
end

Enable the plugin in _config.yml:

# _config.yml
plugins:
  - jekyll-taxonomy-redirects

GitHub Pages: If you deploy with GitHub Pages, build the site in GitHub Actions (or another CI) and deploy the generated _site/ artifact. The hosted Pages builder won’t run third‑party plugins.

Configuration

Add a taxonomy_redirects: block to _config.yml.

taxonomy_redirects:
  # Optional: roots redirect to the new sections
  roots:
    - from: "/category"
      to:   "/venues"
    - from: "/tags"
      to:   "/acts"

  # Per‑slug redirects driven by your content’s taxonomies
  maps:
    - type: "category"   # or "tag"
      from: "/category"
      to:   "/venues"
    - type: "tag"
      from: "/tags"
      to:   "/acts"

  # HTML output tweaks
  emit_canonical: true    # add <link rel="canonical" href="…"> (default: true)

What gets generated

With the configuration above, the plugin creates:

/category/ → /venues/
/tags/ → /acts/
/category/<slug>/ → /venues/<slug>/
/tags/<slug>/ → /acts/<slug>/

It discovers the <slug> values from site.categories.keys and site.tags.keys at build time.

The plugin runs late (priority :low) so taxonomies from your content are available.

How it works

For each redirect, the plugin writes a minimal index.html containing:

<!doctype html>
<meta http-equiv="refresh" content="0; url=/new/path/">
<link rel="canonical" href="/new/path/">
<script>location.replace('/new/path/');</script>
<p>Moved to <a href="/new/path/">/new/path/</a>.</p>

This approach is portable across static hosts (including GitHub Pages). If your host supports server‑side rules (e.g. Netlify), you can keep using this, or open an issue to add an optional provider file emitter.

Example: WordPress → Jekyll (venues/acts)

# _config.yml
plugins:
  - jekyll-archives
  - jekyll-taxonomy-redirects

jekyll-archives:
  enabled: [categories, tags]
  layouts: { category: venue, tag: act }
  permalinks:
    category: /venues/:name/
    tag: /acts/:name/

taxonomy_redirects:
  roots:
    - { from: "/category", to: "/venues" }
    - { from: "/tags",     to: "/acts"   }
  maps:
    - { type: "category", from: "/category", to: "/venues" }
    - { type: "tag",      from: "/tags",     to: "/acts"   }

Now the old /category/foo/ and /tags/bar/ URLs redirect to /venues/foo/ and /acts/bar/.

Compatibility

Jekyll: 4.x
Hosts: Any static host. For GitHub Pages, build the site yourself (Actions) and deploy _site/.
Works with: jekyll-archives, jekyll-redirect-from (for per‑document redirects).

Development

Clone and run against a test site:

bundle install
bundle exec jekyll build --trace

While developing in the same repo as your site, you can point Bundler at the local gem:

# Gemfile in your site
group :jekyll_plugins do
  gem "jekyll-taxonomy-redirects", path: "../jekyll-taxonomy-redirects"
end

Tests

TBD – a minimal fixture site that asserts redirect stubs are created for sample slugs.

Contributing

PRs welcome! Please:

Keep the code tiny and dependency‑free
Add/update docs for any new options
Consider hosts with no server‑side redirect support (keep HTML stubs working)

Versioning & Licence

Versioned with SemVer (0.y.z until the API stabilises)

FAQ

Why not jekyll-redirect-from? That plugin reads front‑matter on individual documents. Archive pages aren’t documents, so there’s nothing to attach front‑matter to. This plugin generates the required stubs for the archive‑style URLs.

Can this emit server 301 rules? On hosts that support provider files (e.g. Netlify _redirects), yes in theory — open an issue. On GitHub Pages, server rules aren’t available, so HTML is the portable choice.

Will this slow down my build? It’s O(N) in the number of category/tag slugs. For typical blogs that’s negligible.