How to validate YAML frontmatter before you build
Updated 2026-06-21
To validate YAML frontmatter, paste the block at the top of your Markdown or MDX file into a validator, pick your framework (Jekyll, Astro, or Next MDX), and check three things: the YAML parses, every required key is present with the right type, and the values are build-safe. The Frontmatter Validator does all three as you type — nothing is uploaded, it runs entirely in your browser.
What "valid" frontmatter actually means
Frontmatter is the block between two --- fences at the top of a content file. It is parsed as YAML, so the first failure point is YAML syntax — an unquoted colon in a title, bad indentation, or a duplicate key. A duplicate key is especially sneaky: YAML does not error, it silently keeps the last value, so your published page shows the wrong title with no warning.
Beyond syntax, "valid" depends on your static site generator. Each one expects a specific set of keys:
- Jekyll requires layout and title.
- Astro content collections typically require title, description and pubDate.
- Next MDX setups commonly expect title, description, date and slug.
A missing required key, or one with the wrong type, is what breaks the build.
Step by step
- Copy the top of your file — either the full document or just the --- block.
- Paste it into the validator and select your framework target.
- Read the key panel: green means present and correctly typed, red means a required key is missing, amber means a type mismatch (for example tags given as a string when a list is expected).
- Fix anything flagged, then copy the normalized YAML it produces.
A worked example: an Astro post with pubDate: June 12 2026 parses as plain text, not a date, so the validator flags it as not a parseable date. Change it to pubDate: 2026-06-12 and it turns green.
The mistakes that pass YAML but break the build
These slip through a raw YAML check yet still cause real problems:
- String instead of a list. Writing tags: react instead of tags: [react] — most SSGs expect an array and throw at build time.
- Unsafe slugs and permalinks. Spaces, uppercase letters, or symbols in a slug or permalink produce ugly or broken URLs. A permalink should also start with a leading slash.
- draft: true. Harmless, but worth a reminder — that page is excluded from your production build.
Don't forget the SEO lengths
Frontmatter is where your title and description meta tags come from, so length matters for how the page shows in search results. The validator checks them live against sensible ranges: roughly 30 to 60 characters for the title and 70 to 160 for the description. It counts visual characters, so an emoji counts as one, not two.
Paste your frontmatter into the Frontmatter Validator and fix every issue before your next build — privately, with nothing leaving your machine.