Parsing Front Matter: front-matter vs gray-matter vs yaml-front-matter

When building static sites, documentation tools, or content management systems, you often need to store metadata at the top of a file. This is called "front matter." It usually sits between delimiters (like ---) and contains YAML, JSON, or TOML. Three common packages handle this in the JavaScript ecosystem: front-matter, gray-matter, and yaml-front-matter. While they solve the same problem, their capabilities and maintenance status vary widely.

🛠️ Core Parsing Capabilities: YAML vs JSON vs TOML

The most critical difference is what data formats each package supports out of the box.

front-matter focuses primarily on YAML.

• It uses the js-yaml library under the hood.
• It is strict about YAML syntax by default.
• Does not support JSON or TOML without custom configuration.

// front-matter: YAML only by default
import fm from 'front-matter';

const file = `---
title: Hello
---
Content here`;

const result = fm(file);
console.log(result.attributes.title); // "Hello"

gray-matter supports multiple languages natively.

• You can parse YAML, JSON, and even TOML.
• It auto-detects the language based on delimiters or options.
• Great for projects mixing different config formats.

// gray-matter: Multi-language support
import matter from 'gray-matter';

// YAML
const yamlFile = matter(`---
title: Hello
---
Content`);

// JSON
const jsonFile = matter(`+++json
{
  "title": "Hello"
}
+++
Content`);

console.log(yamlFile.data.title); // "Hello"
console.log(jsonFile.data.title); // "Hello"

yaml-front-matter is strictly for YAML.

• As the name implies, it does not handle JSON or TOML.
• It is older and less flexible than gray-matter.
• Best suited for legacy projects that specifically require this narrow scope.

// yaml-front-matter: Strictly YAML
import yfm from 'yaml-front-matter';

const file = `---
title: Hello
---
Content here`;

const result = yfm.loadFront(file);
console.log(result.title); // "Hello"
// Note: API returns attributes directly on the object, not nested

🔧 API Design: Object Structure and Stringifying

How you access the data and write it back differs between these libraries. This affects how much boilerplate code you write.

front-matter returns a structured object.

• attributes holds the metadata.
• body holds the content.
• Does not have a built-in way to write front matter back to a string easily.

// front-matter: Read-only structure
import fm from 'front-matter';

const result = fm(file);
const meta = result.attributes;
const content = result.body;

// No built-in stringify method to reconstruct the file

gray-matter offers a symmetric API (read and write).

• data holds the metadata.
• content holds the body.
• Includes .stringify() to write changes back to disk cleanly.

// gray-matter: Read and Write
import matter from 'gray-matter';

const file = matter(fileString);
file.data.title = "Updated Title";

// Reconstruct the file with new front matter
const newFile = matter.stringify(file.content, file.data);

yaml-front-matter merges metadata into the result.

• The returned object contains both content and attributes mixed.
• __content property usually holds the body.
• Less clear separation of concerns compared to gray-matter.

// yaml-front-matter: Merged result
import yfm from 'yaml-front-matter';

const result = yfm.loadFront(file);
const title = result.title; // Direct access
const content = result.__content; // Body is a property

// No built-in stringify method

⚙️ Customization: Delimiters and Engines

Real-world projects often need custom delimiters (like +++ for Hugo) or custom parsing logic.

front-matter allows some delimiter config.

• You can change the opening and closing markers.
• Limited ability to swap the parsing engine.

// front-matter: Custom delimiters
import fm from 'front-matter';

// Configuring delimiters is less straightforward 
// often requires passing options to the function if supported
// or relying on default '---'
const result = fm(file, { delimiters: '+++' }); 

gray-matter is highly extensible.

• Easily change delimiters (e.g., +++ for TOML).
• You can plug in custom engines for exotic formats.
• Supports strict mode to fail on invalid YAML.

// gray-matter: Custom delimiters and engines
import matter from 'gray-matter';

// Using +++ for TOML or custom YAML
const file = matter(fileString, {
  delimiters: '+++',
  engines: {
    yaml: require('js-yaml').safeLoad
  }
});

yaml-front-matter has minimal configuration.

• Mostly sticks to defaults.
• Harder to adapt for non-standard project structures.
• Lacks the plugin architecture of gray-matter.

// yaml-front-matter: Limited config
import yfm from 'yaml-front-matter';

// Mostly relies on default '---' delimiters
// Harder to customize parsing behavior
const result = yfm.loadFront(file);

🚨 Maintenance and Ecosystem Health

This is a critical architectural decision factor. Using unmaintained packages introduces security and compatibility risks.

front-matter is stable but slower moving.

• It is widely used and considered reliable for YAML.
• Updates are infrequent but it remains functional.
• Good for simple, long-term stable projects.

gray-matter is the active standard.

• Maintained by prominent ecosystem contributors.
• Regularly updated to fix bugs and support new Node versions.
• Used by major tools like VuePress and many static site generators.

yaml-front-matter is effectively legacy.

• Development has slowed significantly.
• Many modern tools have migrated away from it to gray-matter.
• Not recommended for new architecture unless required for legacy compatibility.

📊 Summary Table

💡 The Big Picture

gray-matter is the clear winner for modern development. It handles the complexity of different formats, allows you to write data back to files easily, and is actively maintained. It saves you from writing boilerplate code to handle edge cases.

front-matter is a decent runner-up if you only care about YAML and want a very lightweight dependency without the extra features of gray-matter. It is safe to use but offers less flexibility.

yaml-front-matter should generally be avoided in new projects. It lacks the features and maintenance cadence of the other two. Only use it if you are stuck maintaining an older system that depends on its specific API behavior.

Final Thought: In 2024 and beyond, gray-matter is the architectural standard for front matter parsing. It balances power, flexibility, and stability better than the alternatives.