gray-matter
Front matter parser for Markdown and other text files. Extracts YAML, TOML, JSON, or JavaScript front matter from text content — the metadata block delimited by --- at the top of Markdown files. Used by nearly every static site generator (Gatsby, Next.js, Vite/Vitepress, Hugo-like tools) to parse page metadata. Returns {data, content} where data is the parsed front matter and content is the body text.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Text parsing utility — no network surface. YAML parsing is safe (js-yaml uses safe load by default). JavaScript front matter engine executes code — restrict to trusted content only.
⚡ Reliability
Best When
You're building a static site generator, CMS, or content pipeline that processes Markdown files with YAML/TOML/JSON front matter metadata.
Avoid When
You need to render Markdown (use marked/remark) or parse YAML files without front matter context (use js-yaml).
Use Cases
- • Parse Markdown blog posts extracting title, date, tags, and author from YAML front matter for static site generators
- • Build content management systems that store metadata alongside Markdown content in front matter
- • Process documentation files in content pipelines extracting SEO metadata, sidebar navigation, and page config
- • Parse MDX or MDsveX files with front matter in React/Svelte component documentation systems
- • Extract configuration from text files in build tools that use front matter to annotate source files
Not For
- • Markdown rendering — gray-matter parses front matter only; use marked, remark, or markdown-it for Markdown to HTML rendering
- • YAML parsing outside of front matter — use js-yaml for general YAML parsing
- • Non-text file metadata — gray-matter handles text files with front matter delimiters only
Interface
Authentication
No authentication — file parsing utility.
Pricing
Fully free, MIT licensed.
Agent Metadata
Known Gotchas
- ⚠ Files without front matter return empty data object — matter(content).data is {} if no front matter exists; files with and without front matter are handled consistently
- ⚠ YAML front matter type coercion: YAML 1.2 treats 'yes'/'no' as boolean, 'null' as null — use quotes for string values that might be misinterpreted as booleans
- ⚠ Multiline YAML strings in front matter require proper YAML block scalar syntax (| for literal, > for folded) — forgetting this produces single-line strings with literal \n
- ⚠ excerpt option extracts text after front matter but before a separator — useful for preview text; configure excerpt_separator to match your content convention
- ⚠ matter.data is a shallow parse — nested YAML objects work, but complex JavaScript expressions (JS front matter) require engines: { js: { evaluate: ... } } configuration
- ⚠ Leading/trailing whitespace in front matter values: YAML trims string values by default — verify your front matter values don't have significant leading/trailing spaces
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for gray-matter.
Scores are editorial opinions as of 2026-03-06.