Markdown Front Matter Mistakes That Don't Throw an Error
Front matter failures come in two kinds. The loud kind breaks the build, prints a filename and a line number, and gets fixed in about ninety seconds. The quiet kind lets the build pass, renders the page, and removes the post from your archive listing — and you find out three weeks later when someone asks why an article they remember writing isn't on the site. This is about the second kind, because those are the ones worth being able to spot deliberately.
What they have in common: every file involved is individually valid. The YAML parses. A validator says it's fine. The problem exists only in the relationship between files, or between a file and what your template expects, and neither of those is something a single-file check can see.
The same field under two names
This is the most common silent failure and the most expensive. Your template reads date. One post — written months later, or by someone else, or copied from a different project's boilerplate — uses publishDate. Nothing errors. The template asks for a field that isn't there, gets nothing back, and renders an empty string. Depending on your setup, the post sorts to the bottom of the list, or shows a blank date, or drops out of a collection filtered on that field entirely.
The variants multiply quickly: description and summary, tags and categories, image and cover, author and authors. Framework migrations are a common source — Jekyll conventions carried into an Astro project, or Hugo defaults mixed with hand-written files — as is any content folder more than one person has touched.
The reliable signal that two names are one field is that no single file uses both. If half your posts have date and half have publishDate and none have both, that's not two fields, it's one field spelled two ways. If a post has title and subtitle together, those genuinely are separate fields. That distinction is only visible when you look at the whole folder at once, which is exactly why this survives file-by-file review.
Duplicate keys keep the last value and say nothing
Write the same key twice in one block and you don't get an error from most generators — you get the last value, and the first one vanishes. It happens naturally: you add description near the top while editing, not noticing there's already one eight lines down. The rendered page uses the second, and the version you actually wrote is gone with no indication anything was dropped.
Strict YAML parsers do reject duplicate mapping keys, and some toolchains surface that. But plenty of setups don't, and the failure is invisible in an editor because both lines are right there looking perfectly reasonable.
Fence rules that void the whole block
Front matter has to be the very first thing in the file. Not the first meaningful thing — the first thing. A single blank line above the opening --- and most parsers stop treating the block as front matter at all; instead of metadata, you get a horizontal rule and a wall of raw title: ... text rendered into the page body. This is a favorite outcome of copy-paste and of editors that add a trailing newline in the wrong place.
Two related ones. An unclosed fence swallows however much of your post sits before the next --- it happens to find, which in a post that uses horizontal rules can be an arbitrary chunk of the article. And a byte-order mark at the start of the file sits invisibly before the opening fence, so the parser sees a character it wasn't expecting where the delimiter should be — Jekyll's own documentation is unusually blunt about this, warning that very bad things happen if a BOM is present, which is mainly a hazard on Windows editors.
Type drift: a list in forty files, a string in one
YAML lets you write a single-item list as either a proper list or a bare scalar, and both look correct:
tags: - guide # a list with one item tags: guide # a string, not a list
A template that iterates over tags will loop over the list fine. Handed the string, it may iterate over its characters, render nothing, or throw — and which of those you get depends on the generator. The page that produces five tag links reading "g", "u", "i", "d", "e" is the memorable version; the silent one, where the post just never appears on any tag page, is the common one.
The same drift hits booleans. draft: false is a boolean, draft: "false" is a non-empty string, and a template testing truthiness treats the second as true — which means the post you marked as published stays hidden, or the draft you meant to hide gets published. This is a specific instance of YAML's broader type-inference behavior, which is worth understanding in general if you write much YAML.
Dates that parse but don't agree
Three posts using 01/12/2026 while everything else uses 2026-01-12 is a real problem hiding behind two valid-looking values. Beyond the day/month ambiguity, a generator that parses one shape and not the other will sort those posts to wherever unparseable dates land — usually the very top or the very bottom of your archive.
Quoting matters here too. In YAML, an unquoted 2026-01-12 can be interpreted as a date value while "2026-01-12" is unambiguously a string, and generators differ in what they do with each. Neither is wrong; being inconsistent about it across a folder is what causes trouble. If your dates render differently on posts that look identical in source, quoting is the first thing to check.
Two posts fighting over one URL
Duplicate slug, permalink, or url values mean two files resolve to the same output path. Some generators error, some warn, and some just write one file over the other — leaving you with a post that exists in the repo, builds without complaint, and returns a page containing someone else's content. Duplicate titles are milder but worth knowing about, since they usually mean either an accidental copy or two posts competing for the same search query.
Checking the whole folder at once
Every failure above is invisible in a single file and obvious across a batch. Naming drift needs the other files to compare against. Type drift needs a majority to drift from. Duplicate slugs need at least two posts by definition. A YAML validator can't help, because nothing here is a YAML error.
If you want this enforced automatically, a schema is the right answer — Astro validates content collections against a Zod schema at build time and fails with the offending file and field, and equivalent CLI validators exist for other generators and wire into CI. That catches problems on commit, which is the right place to catch them.
For the moment you're actually staring at a folder wondering what's inconsistent, FreeToolDev's Bulk Markdown Front Matter Checker compares posts against each other in the browser: field names that never co-occur, types that change between files, mixed date formats, duplicate slugs, and per-file fence and required-field problems. Paste the posts in, nothing is uploaded. If your front matter also carries the title and description your pages publish as meta tags, the bulk meta length checker is the natural next pass, and this post covers the sitemap side of running a static site.