// the find
jonschlinkert/gray-matter
Smarter YAML front matter parser, used by metalsmith, Gatsby, Netlify, Assemble, mapbox-gl, phenomic, vuejs vitepress, TinaCMS, Shopify Polaris, Ant Design, Astro, hashicorp, garden, slidev, saber, sourcegraph, and many others. Simple to use, and battle tested. Parses YAML by default but can also parse JSON Front Matter, Coffee Front Matter, TOML Front Matter, and has support for custom parsers. Please follow gray-matter's author: https://github.com/jonschlinkert
gray-matter is the de facto standard for parsing YAML front matter from Markdown and HTML files in the JavaScript ecosystem. It splits a string into its front-matter data object and body content, with support for YAML, JSON, TOML, and custom parsers. If you're building a static site generator, docs pipeline, or anything that reads content files with metadata headers, this is the library you reach for.
Used in production by Gatsby, Astro, Vitepress, and Sourcegraph — the adoption list is long enough that the edge cases are genuinely battle-tested. The engine plugin system is clean: drop in a TOML parser as a one-liner and it just works. Auto-detection of the front-matter language from the opening delimiter tag (```---toml```) is a nice touch that avoids per-file configuration. The stringify round-trip works correctly, which most front-matter parsers skip entirely.
Last meaningful commit was mid-2023 and the project is essentially in maintenance mode — issues pile up unanswered. No async API, which matters if you're processing thousands of large files and want to avoid blocking the event loop. The TypeScript definitions in gray-matter.d.ts are hand-maintained and have drifted; the excerpt function overload types in particular are loose enough to let type errors through at runtime. bower.json and .travis.yml in the repo are fossils — the tooling story hasn't been touched in years.