md-schema

Typed frontmatter schemas for markdown documents.

@holdenmatt/md-schema parses Markdown with YAML frontmatter and validates the frontmatter with a Zod object schema. The markdown body is returned as trimmed markdown text.

Install

npm add @holdenmatt/md-schema zod

Usage

import { z } from "zod";
import { markdownSchema } from "@holdenmatt/md-schema";

const postSchema = markdownSchema(
  z.object({
    title: z.string(),
    draft: z.boolean().default(false),
    slug: z.string().transform((value) => value.toLowerCase()),
  }),
);

const result = postSchema.parse(`---
title: Hello
slug: Hello-World
---

# Hello
`);

if (result.success) {
  result.data.frontmatter.title;
  result.data.body;
  result.data.markdown;
}

API

markdownSchema(frontmatterSchema)

Creates a parser for markdown documents with YAML frontmatter.

• frontmatterSchema: a Zod object schema used to validate parsed frontmatter.
• Returns { schema, parse }.
• schema is the original Zod schema.
• parse(markdown) returns a safe result object and does not throw for parser or Zod validation failures.

Success:

{
  success: true,
  data: {
    frontmatter,
    body,
    markdown,
  },
}

Failure:

{
  success: false,
  error,
}

Only frontmatter is validated. The body is not parsed and is returned as trimmed markdown text.

Parsing is delegated to @holdenmatt/md-parser; md-schema is responsible for Zod validation and typed result shaping.