Two h1 tags on 500 pages: the bug that lives between two correct halves

Zugo — Sat, 01 Aug 2026 22:20:43 +0000

Our blog grew from 84 posts to 1,360 in a day. Then I read one live page instead of the source, counted tags, and found two <h1> elements on 500 of them. Both halves of the code were correct. Their sum was not, and no test could see it.

Where the second heading came from

The post template prints the title from frontmatter:

<h1>${esc(fm.title)}</h1>

Every article starts with its own heading, because that is what a markdown document looks like:

# How to build a CRM without code

marked turns that into another <h1>. Nothing in either file is wrong. A markdown document that opens with a level-one heading is correct markdown. A template that prints the page title as the page heading is a correct template. The defect exists only in the output, which is the one artifact nobody was testing.

Why the tests were green

The suite had guards for the corpus and guards for the renderer:

Guard	What it read	Would it catch two h1?
corpus checker	the `.md` files	no, markdown was valid
template tests	the component	no, template emits one
build	exit code	no, build succeeded

Every one of them passed, forever, while a thousand pages shipped a broken heading hierarchy. Search engines get to pick which heading is the page title in that situation, and screen readers announce a structure that does not exist.

The fix is one line, in one place

Not in 500 files. The markdown is not at fault, so editing it would be fixing the wrong thing.

const html = marked.parse(body)
  .replace(/<h1(\s[^>]*)?>/g, "<h2$1>")
  .replace(/<\/h1>/g, "</h2>");

Demoted rather than deleted: if the body heading ever diverges from the frontmatter title, the text stays on the page instead of vanishing silently.

The part worth stealing

The gate runs on the finished page, not on the inputs:

const h1s = (page.match(/<h1[\s>]/g) ?? []).length;
if (h1s !== 1) fail(`${slug}: ${h1s} h1 tags, expected exactly one`);

It is three lines and it catches a whole class. I verified it by mutation: remove the demotion and the build fails on the first article, which is the only evidence that a green gate means anything.

Counting things that must be unique is cheap and it works for more than headings. canonical, title, og:url all have the same property: exactly one, always, and a duplicate is invisible until someone looks at the output.

The general shape

When both sides of a seam look correct and the result is wrong, check the output, not the inputs. I hit the same shape twice more the same week: a checker that read the source and passed while the built HTML was broken, and a guard that fired on correct text because it matched a substring instead of a structure.

If your site generator has a template and a content directory, you probably have a version of this. It costs one command to find out:

grep -c '<h1' dist/some/page/index.html