2 minute read

🧠 The Problem

While building my Jekyll site, I ran into a subtle but very real production issue: stale URLs after renaming a post.

After renaming a markdown file that had already been rendered, Jekyll began throwing errors like:

ERROR '/blog/2026/01/11/did-small-jekyll-build-blog-intro.html' not found

The confusing part was that the file no longer existed. I had renamed it, rebuilt the site, and even deleted the _site/ directory.

So why was Jekyll still looking for it?

🔍 Root Cause

There were two things happening at once.

1️⃣ A stale URL was still being referenced

Once Jekyll generates a page, that URL may be referenced by:

  • archive pages
  • RSS feeds
  • internal links
  • browser cache

Static site generators don’t automatically forget old paths. If a URL ever existed, something may still try to request it.

2️⃣ Front matter was accidentally altered

At one point, my markdown editor rewrote part of the front matter and injected extra metadata. In the process, required fields were modified, causing Jekyll to treat the post inconsistently.

The result: valid content pointing to an invalid URL — classic 404 territory.

🛠️ The Fix

I fixed this cleanly using two deliberate steps.

✅ Add redirects for renamed posts

I added the following to the effected post’s front matter:

redirect_from:
  - /blog/2026/01/11/did-small-jekyll-build-blog-intro.html
  - /2026/01/11/did-small-jekyll-build-blog-intro.html

This tells Jekyll:

If anyone (or anything) requests the old URL, redirect them to the new one.

No hacks. No broken links. No SEO damage.

✅ Lock in clean, minimal front matter

I removed editor-specific metadata and standardized on a small, predictable set of fields:

  • layout
  • title
  • categories
  • tags
  • excerpt

Less magic = fewer surprises.

🧠 Why This Works

Jekyll doesn’t forget URLs.

If a page was ever generated, something may still try to access it.

This is not a bug — it’s how static site generators preserve link integrity.

The correct solution is not deleting files randomly, but redirects and consistency, which is exactly how production websites preserve SEO and user trust.

🚀 Hardening the Setup (Recommended Upgrade)

To prevent this class of issue going forward, I standardized my blog URLs in _config.yml:

permalink: /blog/:year/:month/:day/:title:output_ext

Why this helps

  • All blog content lives under /blog/
  • URLs are predictable and human-readable
  • Renames are less likely to cause accidental 404s
  • This structure is common, professional, and SEO-friendly

✅ Prevention: A Pro Jekyll Workflow

Draft phase

  • Rename freely
  • No redirects needed

Publish phase

  • Choose final filename
  • Lock the slug
  • Only change the title

If renamed after publish

  • Add redirect_from
  • Rebuild
  • Move on

🧩 Final Takeaway

What looked like a frustrating bug turned out to be a valuable lesson in:

  • how Jekyll generates and preserves URLs
  • why front matter consistency matters
  • how production sites handle change safely

This isn’t something you learn from a “Hello World” tutorial — you learn it by building, breaking, and fixing.

And now it’s documented, reproducible, and part of my workflow.

Updated: