@holdenmatt/md-parser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Holden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# md-parser
+
+Markdown parser primitives for frontmatter, body text, sections, and code blocks.
+
+`@holdenmatt/md-parser` provides shared Markdown parser primitives for generic document structure. It parses untyped frontmatter, frontmatter-free body text, flat heading sections, and code blocks without assigning application meaning to the content.
+
+## Install
+
+```sh
+npm install @holdenmatt/md-parser
+```
+
+## Usage
+
+```ts
+import { parse, stringify } from "@holdenmatt/md-parser";
+
+const document = parse(`---
+title: Example
+---
+
+## Notes
+
+Body text.
+`);
+
+document.raw; // original markdown
+document.frontmatter; // Record<string, unknown>
+document.body; // markdown without frontmatter
+document.sections[0]?.heading; // "Notes"
+document.codeBlocks; // fenced and indented code blocks
+
+const markdown = stringify({
+  frontmatter: { title: "Example" },
+  body: "## Notes\n\nBody text.\n",
+});
+```
+
+## API
+
+### `parse(markdown)`
+
+Parses a Markdown string and returns a `MarkdownDocument`.
+
+### `parseFile(path)`
+
+Reads a UTF-8 Markdown file and returns a `Promise<MarkdownDocument>`.
+
+### `stringify({ frontmatter, body })`
+
+Serializes frontmatter and body text back into Markdown. Empty or omitted frontmatter returns the body unchanged.
+
+### `MarkdownDocument`
+
+`parse` returns one canonical document shape:
+
+```ts
+type MarkdownDocument = {
+  raw: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+  sections: MarkdownSection[];
+  codeBlocks: MarkdownCodeBlock[];
+};
+```
+
+Frontmatter is intentionally untyped. Application packages can refine it with their own schemas, or use [`@holdenmatt/md-schema`](https://github.com/holdenmatt/md-schema) for typed frontmatter parsing.
+
+Parse and file-read failures throw `MarkdownParseError`. See [SPEC.md](./SPEC.md) for the structural parsing contract.

package/SPEC.md

@@ -0,0 +1,39 @@
+# md-parser spec
+
+md-parser parses one Markdown document into stable structural views and can stringify frontmatter plus body text back into Markdown.
+
+## Scope
+
+- md-parser parses document structure, not document meaning.
+- Frontmatter remains untyped; application packages refine it.
+- The package does not define application semantics for headings, code block languages, directives, macros, or other Markdown content.
+
+## Parse
+
+- `parse(markdown)` returns `{ raw, frontmatter, body, sections, codeBlocks }`.
+- `raw` is the original input string.
+- `frontmatter` is parsed YAML data or `{}`.
+- Invalid frontmatter fails.
+- `body` is Markdown with frontmatter removed.
+- `parseFile(path)` reads UTF-8 text before parsing.
+- Parse and file failures throw `MarkdownParseError`.
+- The public `MarkdownDocument` shape does not expose the internal Markdown AST.
+
+## Sections
+
+- Sections are a flat list built from body headings.
+- A section owns content until the next heading of the same or shallower depth.
+- Section body text is trimmed of surrounding blank lines.
+- Section headings are plain readable text.
+
+## Code Blocks
+
+- Code blocks come from the parsed body structure.
+- Each block exposes `info`, `language`, `meta`, and `value`.
+- Code block language and metadata are not interpreted.
+
+## Stringify
+
+- `stringify({ frontmatter, body })` serializes frontmatter and body text.
+- Empty or omitted frontmatter returns the body unchanged.
+- Stringify does not use `sections` or `codeBlocks`.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { MarkdownParseError, parse, parseFile } from "./parse.js";
+export { stringify } from "./stringify.js";
+export type { MarkdownCodeBlock, MarkdownDocument, MarkdownSection } from "./parse.js";
+export type { MarkdownStringifyInput } from "./stringify.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { MarkdownParseError, parse, parseFile } from "./parse.js";
+export { stringify } from "./stringify.js";

package/dist/parse.d.ts

@@ -0,0 +1,55 @@
+/** Error thrown when parsing or file reading fails. */
+export declare class MarkdownParseError<TCode extends string = string> extends Error {
+    /** Machine-readable error code. */
+    readonly code: TCode;
+    /** Original error or diagnostic details, when available. */
+    readonly details: unknown;
+    constructor(code: TCode, message: string, details?: unknown);
+}
+/**
+ * Parsed markdown document with raw text and structural views of the body.
+ */
+export type MarkdownDocument = {
+    /** Original input markdown. */
+    raw: string;
+    /** Parsed frontmatter data, or an empty object when no frontmatter exists. */
+    frontmatter: Record<string, unknown>;
+    /** Markdown body with any frontmatter removed. */
+    body: string;
+    /** Flat heading sections from the body. */
+    sections: MarkdownSection[];
+    /** Code blocks from the body. */
+    codeBlocks: MarkdownCodeBlock[];
+};
+/**
+ * Markdown body content owned by a heading.
+ */
+export type MarkdownSection = {
+    /** Plain text heading content. */
+    heading: string;
+    /** Markdown heading depth, from 1 through 6. */
+    depth: number;
+    /** Section content until the next same-or-higher heading. */
+    body: string;
+};
+/**
+ * Markdown code block from the body.
+ */
+export type MarkdownCodeBlock = {
+    /** Full code fence info string, reconstructed from language and meta. */
+    info: string;
+    /** Code fence language, when present. */
+    language: string | undefined;
+    /** Code fence metadata after the language, when present. */
+    meta: string | undefined;
+    /** Code block content. */
+    value: string;
+};
+/**
+ * Parse markdown into one canonical document shape.
+ */
+export declare function parse(markdown: string): MarkdownDocument;
+/**
+ * Read a UTF-8 markdown file and parse it.
+ */
+export declare function parseFile(path: string): Promise<MarkdownDocument>;

package/dist/parse.js

@@ -0,0 +1,138 @@
+import { readFile } from "node:fs/promises";
+import matter from "gray-matter";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+/** Error thrown when parsing or file reading fails. */
+export class MarkdownParseError extends Error {
+    /** Machine-readable error code. */
+    code;
+    /** Original error or diagnostic details, when available. */
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "MarkdownParseError";
+        this.code = code;
+        this.details = details;
+    }
+}
+const markdownParser = unified().use(remarkParse);
+/**
+ * Parse markdown into one canonical document shape.
+ */
+export function parse(markdown) {
+    let parsed;
+    try {
+        parsed = matter(markdown);
+    }
+    catch (error) {
+        throw new MarkdownParseError("FRONTMATTER_PARSE_ERROR", "Could not parse markdown frontmatter.", error);
+    }
+    try {
+        const ast = markdownParser.parse(parsed.content);
+        return {
+            raw: markdown,
+            frontmatter: toFrontmatterRecord(parsed.data),
+            body: parsed.content,
+            sections: extractSections(parsed.content, ast),
+            codeBlocks: extractCodeBlocks(ast),
+        };
+    }
+    catch (error) {
+        throw new MarkdownParseError("MARKDOWN_PARSE_ERROR", "Could not parse markdown body.", error);
+    }
+}
+/**
+ * Read a UTF-8 markdown file and parse it.
+ */
+export async function parseFile(path) {
+    try {
+        return parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof MarkdownParseError)
+            throw error;
+        throw new MarkdownParseError("FILE_READ_ERROR", `Could not read file: ${path}`, error);
+    }
+}
+/**
+ * Build flat heading sections from body offsets reported by mdast.
+ */
+function extractSections(body, ast) {
+    const headings = ast.children
+        .map((node, index) => (node.type === "heading" ? { node, index } : undefined))
+        .filter((item) => item !== undefined);
+    return headings.flatMap(({ node }, index) => {
+        const start = node.position?.end.offset;
+        if (start === undefined)
+            return [];
+        const next = headings.slice(index + 1).find((heading) => heading.node.depth <= node.depth);
+        const end = next?.node.position?.start.offset ?? body.length;
+        return [
+            {
+                heading: textFromNode(node),
+                depth: node.depth,
+                body: trimBlankLines(body.slice(start, end)),
+            },
+        ];
+    });
+}
+/**
+ * Collect code blocks without assigning meaning to their language.
+ */
+function extractCodeBlocks(ast) {
+    const blocks = [];
+    visit(ast, (node) => {
+        if (node.type !== "code")
+            return;
+        const code = node;
+        const language = code.lang ?? undefined;
+        const meta = code.meta ?? undefined;
+        const info = [language, meta].filter((value) => value !== undefined && value !== "").join(" ");
+        blocks.push({
+            info,
+            language,
+            meta,
+            value: code.value,
+        });
+    });
+    return blocks;
+}
+/**
+ * Walk the mdast tree depth-first.
+ */
+function visit(node, visitor) {
+    visitor(node);
+    if (!("children" in node))
+        return;
+    for (const child of node.children) {
+        visit(child, visitor);
+    }
+}
+/**
+ * Collapse a heading node to its readable text.
+ */
+function textFromNode(node) {
+    if ("value" in node && typeof node.value === "string")
+        return node.value;
+    if (!("children" in node))
+        return "";
+    return node.children.map((child) => textFromNode(child)).join("");
+}
+/**
+ * Remove blank padding around extracted section bodies.
+ */
+function trimBlankLines(value) {
+    return value.replace(/^(?:[ \t]*\r?\n)+/, "").replace(/(?:\r?\n[ \t]*)+$/, "");
+}
+/**
+ * Keep the public frontmatter shape object-like and predictable.
+ */
+function toFrontmatterRecord(value) {
+    return isPlainRecord(value) ? value : {};
+}
+/**
+ * Check for a non-array object suitable for frontmatter data.
+ */
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/stringify.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Source fields needed to serialize a markdown document.
+ */
+export type MarkdownStringifyInput = {
+    /** Frontmatter data to write, or omit for a plain body-only document. */
+    frontmatter?: Record<string, unknown>;
+    /** Markdown body text. */
+    body: string;
+};
+/**
+ * Serialize frontmatter and body back into markdown.
+ */
+export declare function stringify(input: MarkdownStringifyInput): string;

package/dist/stringify.js

@@ -0,0 +1,15 @@
+import matter from "gray-matter";
+/**
+ * Serialize frontmatter and body back into markdown.
+ */
+export function stringify(input) {
+    if (!hasFrontmatter(input.frontmatter))
+        return input.body;
+    return matter.stringify(input.body, input.frontmatter);
+}
+/**
+ * Check whether frontmatter should be emitted.
+ */
+function hasFrontmatter(value) {
+    return value !== undefined && Object.keys(value).length > 0;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@holdenmatt/md-parser",
+  "version": "0.1.0",
+  "description": "Markdown parser primitives for frontmatter, body text, sections, and code blocks.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holdenmatt/md-parser.git"
+  },
+  "files": [
+    "dist",
+    "SPEC.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "check": "pnpm format:check && pnpm lint && pnpm test && pnpm typecheck && pnpm build"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^26.0.1",
+    "oxfmt": "^0.56.0",
+    "oxlint": "^1.71.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "packageManager": "pnpm@10.33.0"
+}