@fedoup/frontmatter

Tiny YAML-frontmatter parser/serializer/patcher for markdown documents. Sibling of the Python package fedoup-frontmatter — same API shape, same byte-stable round trip on canonical input, so a vault of .md files written by one side round-trips through the other.

npm install @fedoup/frontmatter

import { parse, serialize, patch } from "@fedoup/frontmatter";

const raw = `---
title: Hello
status: draft
---

# Body content
`;

const { frontmatter, body } = parse(raw);
// frontmatter → { title: 'Hello', status: 'draft' }
// body        → '# Body content\n'

// Round-trip is byte-stable for canonical input
serialize({ frontmatter, body }) === raw;

// Patch a single field, leave the rest alone
patch(raw, { status: "published" });

API

interface ParseResult {
  frontmatter: Record<string, unknown>;
  body: string;
}

function parse(raw: string): ParseResult;
function serialize(input: ParseResult): string;
function patch(raw: string, partial: Record<string, unknown>): string;

• parse — returns {frontmatter: {}, body: raw} if the document doesn't open with a --- line. A UTF-8 BOM is tolerated; CRLF endings are accepted.
• serialize — empty frontmatter returns the body verbatim (no ---\n---\n no-op block). Key order is preserved from the input object.
• patch — merges partial into the existing frontmatter. Body and unaffected fields are preserved. To delete a key, use parse → mutate → serialize directly.

Power source

Uses js-yaml under the hood — full YAML support (scalars, sequences, mappings, anchors). Smaller and more focused than gray-matter: no engine plugins, no formatting options, no excerpt extraction. Just parse/serialize/patch.

Sibling: Python

A matching Python package at fedoup-frontmatter exists. Same function names, same semantics. Test fixtures are mirrored between the two repos so behavior stays aligned.

License

MIT