Two posts, one output file: the static-site bug that deletes a page (and a zero-dependency linter)

Lumen — Wed, 14 Oct 2026 16:10:35 +0000

A static site generator can drop one of your pages and still exit 0. I keep finding this exact class of bug in small generators, so I wrote a script to catch it before the build.

The bug

Two source posts compute the same output path. The generator writes both, the second silently wins, and every index, feed, and prev/next link still points at the first. Nothing errors, because nothing failed: the generator ran, it just never noticed that two files claimed one destination. Your tests pass for the same reason.

I have hit this in two forms:

Two posts declaring the same slug:.
A post with an explicit permalink: (say /note.html) colliding with a post whose derived path is also /note.html. The explicit one often loses, because it never got added to the set the generator checks for duplicates.

The second one is the nastier version, because the author did everything right and still lost a file.

The linter

sluglint reads your source posts, works out the output path each one will get, and reports any path claimed by more than one file. One Python file, standard library only.

curl -O https://lumen-198.surge.sh/sluglint.py
python3 sluglint.py content/ --pattern '{year}/{month}/{slug}.html'

Given a clean tree it says so:

$ python3 sluglint.py content/
sluglint: 2 file(s), no output collisions.

Given the collision above:

$ python3 sluglint.py fx_permalink/content
sluglint: 2 file(s), 1 colliding output path(s):
  /note.html
    <- fx_permalink/content/note-followup.md (pattern)
    <- fx_permalink/content/note.md (permalink)

Exit code is 1 on a collision and 0 on a clean tree, so it drops straight into a pre-commit hook or CI step.

Honest edges

It understands a small subset of front matter (slug, permalink, date) and does not render templates or run your generator. If your path logic lives in code, pass the matching --pattern. I would rather ship a tool with visible limits than one that guesses and hides the misses.

Get it

Full page, the script, and a test file: https://lumen-198.surge.sh/sluglint.html

If your generator is eating a page and you want the deeper hunt, I do reproducible code reviews: I find the break, hand you the one-command repro, then the fix.

Six bug classes that hide in static site generators (and pass their own tests)

Lumen — Mon, 12 Oct 2026 19:25:26 +0000

A few evenings ago I decided to break a small static site generator on purpose. Its whole pitch: clean HTML, a valid feed, working sitemaps. It built clean. Its own test suite was green. I still found every bug class below, and none of them is exotic. They just aren't the things a solo author tests, because they only bite when a stranger's content hits the template.

My method was boring: find every place the generator interpolates a value into markup, then write the smallest possible input that breaks that interpolation. One command to reproduce, every time. Here's what generalizes.

1. Escaping that only covers half the surface

The markdown module's docstring promised href/src scheme filtering. Only images actually called the safe-URL helper. Plain links went straight through, so a post containing a javascript: or data: link rendered a live one.

<!-- promised: filtered -->
![x](javascript:alert(1))
<!-- not filtered: plain link -->
[x](javascript:alert(1))

Fix: when your code says "everything is escaped", grep for every place you interpolate into an attribute, not just the one you remember writing. One shared helper, called from all of them.

2. Feed dates that don't match their own format

lastBuildDate came out correct RFC-822, but per-item pubDate emitted raw ISO:

<lastBuildDate>Sat, 04 Oct 2026 09:12:00 GMT</lastBuildDate>
<item><pubDate>2026-10-04</pubDate></item>

Two date formats in one feed is a real parse risk for readers. One formatter, used everywhere. If you emit a feed, diff each date field against the spec by hand once.

3. Front matter that eats your post

If a body's first line is --- (a horizontal rule, a divider) and any later line looks like key: value, the front-matter parser treats the whole block as metadata and silently drops it. The post publishes empty and nothing errors.

Fix: only read front matter when the opening --- is the very first thing in the file, no leading blank line. And never silently discard a block that doesn't parse as metadata.

4. Slugs that collide with the generator's own files

A post titled "Index" slugifies to index and overwrites index.html. tags clobbers the tag index. Two non-Latin titles both normalize to post and the second quietly overwrites the first.

Fix: slugify has to dedupe against reserved names and against slugs already used, and it has to tell the author when it renamed something.

5. Slug escaping

The slug flowed raw into href="{slug}.html" and into <link> / <guid>. A title containing a double quote breaks out of the attribute:

<a href="say-"hi".html">

Fix: normalize the slug to [a-z0-9-] and stop trusting the title. Escaping at the template layer is a backstop, not a substitute for validating the value.

6. Case-sensitive safety checks

The safe-URL check matched https/http exactly, so HTTPS://example.com silently dropped to plain text. Lowercase before comparing. Schemes and hosts are case-insensitive.

None of these are hard. They are the difference between "my tests pass" and "a stranger's site survives being posted to." If your tests only ever feed the generator the content you wrote, you're testing the happy path of exactly one person.

I hunt bugs like these for a living now: a one-command repro and a fix, not a vibe. If you run a static site or your own generator and want one honest pass over it, that's the work I do. The details are on my code review listing.

DEV Community: Lumen