Two h1 tags on 500 pages: the bug that lives between two correct halves
A developer's lessons on discovering duplicate H1 tags across 500 blog pages where both the source code and templates were entirely correct, yet lacked output-level testing.
Stock photo for illustration only, not from the actual event
- The blog grew from 84 posts to 1,360 in a single day.
- Found two <h1> elements on 500 pages due to overlapping logic between templates and markdown.
- All test suites passed because they only inspected inputs rather than the rendered HTML.
- The issue was easily detectable with a simple output-checking command like grep.
A sudden growth spurt of a blog from 84 posts to 1,360 in a single day led to an unexpected technical discovery. After the developer decided to inspect a live page instead of just the source code, they found two <h1> elements on 500 of them. Both halves of the codebase were correct on their own, but their sum was flawed, and no automated test could detect it.
The issue originated from the post template printing the title from the frontmatter as a level-one heading, while the markdown renderer turned that same title into another <h1> element. Nothing in either file was technically wrong. A markdown document starting with a level-one heading is correct markdown, and a template printing the page title as a heading is a correct template. The defect existed exclusively in the output artifact, which happened to be the one thing nobody was testing.
Stock photo for illustration only, not from the actual event
In software engineering, this scenario highlights the blind spots of testing isolated components or unit inputs while ignoring end-to-end integration results. When independent modules function perfectly on their own, their combined output can still introduce hidden regressions that impact search engine optimization (SEO) and accessibility tools, as screen readers interpret non-existent document structures.
The existing test suite included guards for both the corpus and the renderer, all of which passed indefinitely while a thousand pages shipped with a broken heading hierarchy. Editing the markdown files would have fixed the wrong thing because the markdown itself was never at fault. The verification gate needed to run on the finished page rather than the raw inputs.
Counting items that must be unique is cheap and applies to more than just headings. Elements like canonical tags, titles, and og:url share the exact same property of needing to be singular and unique, yet duplicates remain invisible until someone inspects the output. When both sides of a seam look correct and the result is wrong, engineers should always check the output rather than the inputs.
Source: Dev.to
Found something wrong in this article? Report an issue with this article
Comments
Leave a Comment