2026-09-11 · 8 min read
- markdown
- yaml
- documentation
Front matter places structured metadata before a Markdown document, often between three-dash delimiters. It is a convention implemented by static-site generators and content systems rather than a feature of the core Markdown specification.
Implementations differ on delimiter location, accepted metadata languages, YAML schema, date coercion, duplicate keys, aliases, and unknown fields. A document that previews correctly in one editor can fail a production build or publish with unintended metadata.
Define the file envelope
Specify the text encoding, byte-order-mark policy, line endings, exact opening and closing delimiters, and whether any bytes or blank lines may precede the opening marker. Treat an unclosed front matter block as a build error with a source location.
- Use UTF-8 under a documented BOM policy.
- Keep delimiters alone on their lines.
- Do not let delimiter-like body text terminate metadata.
- Preserve body content independently from metadata parsing.
Validate a narrow metadata schema
Declare required and optional fields with exact types and constraints. Common fields include title, description, publication date, updated date, tags, draft state, canonical source, and layout, but each repository should accept only the values it actually uses.
Quote strings that YAML schemas might interpret as booleans, nulls, numbers, or dates. Convert dates into one explicit calendar or instant model instead of depending on parser-native objects and host timezone defaults.
- Reject duplicate keys before one value silently wins.
- Report unknown fields or intentional extensions consistently.
- Normalize tag arrays without changing meaningful case unexpectedly.
- Keep secrets and deployment credentials out of content metadata.
Separate authoring convenience from build truth
Editors can provide schema completion and previews, but the production parser and validation command remain authoritative. Pin parser behavior, run validation in CI, and produce actionable errors with file, field, and line information.
When migrating generators, compare parsed metadata objects and generated URLs before switching. A parser upgrade can alter scalar resolution even when no source document changed.
Build a portable fixture suite
Use Flashman's Markdown editor and viewer for body fixtures, YAML-to-JSON for non-sensitive metadata, diff for normalized objects and line-ending changes, and case converter for field naming conventions. Flashman does not promise parity with every site's front matter loader.
Test a BOM, leading whitespace, CRLF and LF, empty metadata, quoted and unquoted dates, boolean-like words, null, multiline strings, arrays, duplicate keys, aliases, invalid YAML, Unicode normalization, unknown fields, draft filtering, timezone boundaries, delimiter text in code fences, and old documents during parser or generator upgrades.