datamark() creates a reusable format that parses Markdown into typed objects and optionally serializes them back. It is the single entry point to the Format SDK.

Signature

function datamark<T = unknown, F = Record<string, unknown>>(
  config: FormatConfig<T, F>
): Format<T>;

T — the output type of your format. Inferred from schema if provided, otherwise from parse's return type.
F — the frontmatter type. Inferred from frontmatterSchema if provided, otherwise defaults to Record<string, unknown>.

Quick example

import { datamark } from "datamark";
import { inlineText } from "datamark/parse";
import * as z from "zod";

const BasicSchema = z.object({ title: z.string() });

const BasicFormat = datamark({
  schema: BasicSchema,
  parse(doc) {
    const h1 = doc.root.children.find((n) => n.type === "section") as any;
    return { title: h1 ? inlineText(h1.heading.children) : "" };
  },
});

const result = BasicFormat.parse("# Hello\n\nBody");
// result is typed as { title: string }

FormatConfig

Property	Type	Required	Description
`parse`	`(doc: DocumentWithFrontmatter<F>) => T`	✅	Turns a parsed Markdown document into your typed data. `doc.frontmatter` is typed when `frontmatterSchema` is provided.
`stringify`	`(data: T) => string`	—	Turns typed data back into a Markdown string.
`schema`	`StandardSchemaV1<any, T>`	—	Validates parsed output. `T` is inferred from the schema's output type.
`frontmatterSchema`	`StandardSchemaV1<any, F>`	—	Validates frontmatter before `parse` runs. `F` is inferred from the schema's output type.
`description`	`string`	—	Human-readable description for docs.
`examples`	`FormatExample[]`	—	Inline examples for testing and documentation.
`docs`	`FormatDocs`	—	Extra metadata for generated docs.

When frontmatterSchema is configured, parse() validates frontmatter before your parse function runs. If validation fails, parse() throws ValidationError immediately — your parse function never sees bad frontmatter.

Format methods

`parse(content: string): T`

Parses a Markdown string, validates frontmatter (if frontmatterSchema), runs your parse function, and validates the output (if schema). Returns typed data.

`stringify(data: T): string`

Serializes data back to Markdown using your stringify function.

Throws at runtime if stringify was not configured.

`test(): TestResult`

Runs all configured examples through parse, frontmatter validation, and schema validation. Returns { passed: boolean, failures: Array<{ exampleIndex, example, error }> }.

`docs(): FormatDocs`

Returns metadata: description, examples, and schema output type.

Types reference

`FormatExample`

interface FormatExample {
  text: string;
  data?: unknown;
}

String examples test parseability only. Object examples with data are compared for exact equality.

`DocumentWithFrontmatter<F>`

A Document where frontmatter is typed as F | null instead of Record<string, unknown> | null. This type is automatically applied to the doc parameter in your parse function when frontmatterSchema is configured.

`FormatDocs`

interface FormatDocs {
  description?: string;
  examples?: Array<string | FormatExample>;
  structure?: unknown;
  schema?: unknown;
}

datamark()

On this page