@kubb/parser-md 5.0.0-beta.25

package/README.md

@@ -0,0 +1,92 @@
+<div align="center">
+  <h1>@kubb/parser-md</h1>
+  <a href="https://kubb.dev" target="_blank" rel="noopener noreferrer">
+    <img width="180" src="https://raw.githubusercontent.com/kubb-labs/kubb/main/assets/logo.png" alt="Kubb logo">
+  </a>
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![Coverage][coverage-src]][coverage-href]
+[![License][license-src]][license-href]
+[![Sponsors][sponsors-src]][sponsors-href]
+
+<h4>
+<a href="https://kubb.dev/" target="_blank">Documentation</a>
+<span> · </span>
+<a href="https://github.com/kubb-labs/kubb/issues/" target="_blank">Report Bug</a>
+<span> · </span>
+<a href="https://github.com/kubb-labs/kubb/issues/" target="_blank">Request Feature</a>
+</h4>
+</div>
+
+Markdown source file parser for Kubb. Joins source blocks as plain markdown and renders YAML frontmatter via `parserMd.print`.
+
+## Installation
+
+```bash
+bun add @kubb/parser-md
+# or
+pnpm add @kubb/parser-md
+# or
+npm install @kubb/parser-md
+```
+
+## Usage
+
+```typescript
+import { defineConfig } from 'kubb'
+import { parserMd } from '@kubb/parser-md'
+import { parserTs } from '@kubb/parser-ts'
+
+export default defineConfig({
+  input: { path: './petstore.yaml' },
+  output: { path: './src/gen' },
+  parsers: [parserTs, parserMd],
+})
+```
+
+To convert a metadata object into a YAML frontmatter envelope from inside a plugin, call `print` on the parser instance:
+
+```typescript
+import { parserMd } from '@kubb/parser-md'
+
+const source = parserMd.print({ title: 'Pets', layout: 'doc' })
+// → ---
+//   title: Pets
+//   layout: doc
+//   ---
+```
+
+## API
+
+### `parserMd`
+
+Parser instance for `.md` and `.markdown` files. Pass to `defineConfig({ parsers: [...] })` to emit Markdown source files.
+
+- `parserMd.parse(file)` — serialise a `FileNode` to Markdown source. When `file.meta.frontmatter` is set, the parser prepends the corresponding YAML envelope.
+- `parserMd.print(...parts)` — join markdown fragments separated by blank lines. Plain objects are serialised as YAML frontmatter; strings pass through unchanged.
+
+## Supporting Kubb
+
+Kubb is an open source project with its ongoing development made possible entirely by the support of Sponsors. If you would like to become a sponsor, please consider:
+
+- [Become a Sponsor on GitHub](https://github.com/sponsors/stijnvanhulle)
+
+<p align="center">
+  <a href="https://github.com/sponsors/stijnvanhulle">
+    <img src="https://raw.githubusercontent.com/stijnvanhulle/sponsors/main/sponsors.svg" alt="My sponsors" />
+  </a>
+</p>
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/@kubb/parser-md?flat&colorA=18181B&colorB=f58517
+[npm-version-href]: https://npmjs.com/package/@kubb/parser-md
+[npm-downloads-src]: https://img.shields.io/npm/dm/@kubb/parser-md?flat&colorA=18181B&colorB=f58517
+[npm-downloads-href]: https://npmjs.com/package/@kubb/parser-md
+[license-src]: https://img.shields.io/github/license/kubb-labs/kubb.svg?flat&colorA=18181B&colorB=f58517
+[license-href]: https://github.com/kubb-labs/kubb/blob/main/LICENSE
+[coverage-src]: https://img.shields.io/codecov/c/github/kubb-labs/kubb?style=flat&colorA=18181B&colorB=f58517
+[coverage-href]: https://www.npmjs.com/package/@kubb/parser-md
+[sponsors-src]: https://img.shields.io/github/sponsors/stijnvanhulle?style=flat&colorA=18181B&colorB=f58517
+[sponsors-href]: https://github.com/sponsors/stijnvanhulle/

package/dist/chunk--u3MIqq1.js

@@ -0,0 +1,8 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", {
+	value,
+	configurable: true
+});
+//#endregion
+export { __name as t };

package/dist/index.cjs

@@ -0,0 +1,94 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#endregion
+let _kubb_ast = require("@kubb/ast");
+let _kubb_core = require("@kubb/core");
+let yaml = require("yaml");
+//#region src/utils.ts
+/**
+* Wraps a plain object as a YAML frontmatter envelope:
+*
+* ```
+* ---
+* <yaml>
+* ---
+* ```
+*
+* Returns an empty string for `null`, `undefined`, or empty objects so callers
+* can drop the result through the same filter chain as banner/footer fields.
+*/
+function printFrontmatter(data) {
+	if (!data || Object.keys(data).length === 0) return "";
+	return `---\n${(0, yaml.stringify)(data).trimEnd()}\n---`;
+}
+/**
+* Joins a list of markdown fragments with blank lines. Plain objects are
+* rendered as YAML frontmatter via {@link printFrontmatter}; strings pass
+* through unchanged.
+*
+* @example
+* ```ts
+* print({ title: 'Hi' }, '# Hello')
+* // '---\ntitle: Hi\n---\n\n# Hello'
+* ```
+*/
+function print(...parts) {
+	const rendered = [];
+	for (const part of parts) {
+		if (part === null || part === void 0 || part === "") continue;
+		const text = typeof part === "string" ? part : printFrontmatter(part);
+		if (text) rendered.push(text.trimEnd());
+	}
+	return rendered.join("\n\n");
+}
+//#endregion
+//#region src/parserMd.ts
+/**
+* Kubb parser for `.md` and `.markdown` files. Joins source blocks as plain
+* markdown (separated by blank lines) and, when `file.meta.frontmatter` is set,
+* prepends a YAML frontmatter envelope produced by `parserMd.print`.
+*
+* Add to the `parsers` array on `defineConfig` to opt in. `parserTs` keeps
+* handling `.ts`/`.js` files, `parserMd` claims `.md`/`.markdown`.
+*
+* @example
+* ```ts
+* import { defineConfig } from 'kubb'
+* import { adapterOas } from '@kubb/adapter-oas'
+* import { parserMd } from '@kubb/parser-md'
+*
+* export default defineConfig({
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   adapter: adapterOas(),
+*   parsers: [parserMd],
+*   plugins: [],
+* })
+* ```
+*/
+const parserMd = (0, _kubb_core.defineParser)({
+	name: "markdown",
+	extNames: [".md", ".markdown"],
+	print(...parts) {
+		return print(...parts);
+	},
+	parse(file) {
+		const sourceParts = [];
+		for (const source of file.sources) {
+			const text = (0, _kubb_ast.extractStringsFromNodes)(source.nodes);
+			if (text) sourceParts.push(text.trimEnd());
+		}
+		const body = sourceParts.join("\n\n");
+		const meta = file.meta;
+		const frontmatter = print(meta?.frontmatter ?? void 0);
+		return [
+			file.banner,
+			frontmatter,
+			body,
+			file.footer
+		].filter((segment) => Boolean(segment)).map((segment) => segment.trimEnd()).join("\n\n");
+	}
+});
+//#endregion
+exports.parserMd = parserMd;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/utils.ts","../src/parserMd.ts"],"sourcesContent":["import { stringify } from 'yaml'\n\n/**\n * Markdown `print` input — either a markdown text fragment (passed through\n * verbatim) or a plain object that is serialised as a YAML frontmatter envelope.\n */\nexport type PrintInput = string | Record<string, unknown>\n\n/**\n * Wraps a plain object as a YAML frontmatter envelope:\n *\n * ```\n * ---\n * <yaml>\n * ---\n * ```\n *\n * Returns an empty string for `null`, `undefined`, or empty objects so callers\n * can drop the result through the same filter chain as banner/footer fields.\n */\nexport function printFrontmatter(data: Record<string, unknown> | null | undefined): string {\n  if (!data || Object.keys(data).length === 0) return ''\n  return `---\\n${stringify(data).trimEnd()}\\n---`\n}\n\n/**\n * Joins a list of markdown fragments with blank lines. Plain objects are\n * rendered as YAML frontmatter via {@link printFrontmatter}; strings pass\n * through unchanged.\n *\n * @example\n * ```ts\n * print({ title: 'Hi' }, '# Hello')\n * // '---\\ntitle: Hi\\n---\\n\\n# Hello'\n * ```\n */\nexport function print(...parts: Array<PrintInput | null | undefined>): string {\n  const rendered: string[] = []\n  for (const part of parts) {\n    if (part === null || part === undefined || part === '') continue\n    const text = typeof part === 'string' ? part : printFrontmatter(part)\n    if (text) rendered.push(text.trimEnd())\n  }\n  return rendered.join('\\n\\n')\n}\n","import type { CodeNode } from '@kubb/ast'\nimport { extractStringsFromNodes } from '@kubb/ast'\nimport { defineParser } from '@kubb/core'\nimport { print, type PrintInput } from './utils.ts'\n\n/**\n * Metadata accepted by `parserMd`. Set `frontmatter` on a `<File meta={…}>` to\n * have the parser prepend the corresponding YAML envelope.\n */\nexport type MdMeta = {\n  frontmatter?: Record<string, unknown> | null\n}\n\n/**\n * Kubb parser for `.md` and `.markdown` files. Joins source blocks as plain\n * markdown (separated by blank lines) and, when `file.meta.frontmatter` is set,\n * prepends a YAML frontmatter envelope produced by `parserMd.print`.\n *\n * Add to the `parsers` array on `defineConfig` to opt in. `parserTs` keeps\n * handling `.ts`/`.js` files, `parserMd` claims `.md`/`.markdown`.\n *\n * @example\n * ```ts\n * import { defineConfig } from 'kubb'\n * import { adapterOas } from '@kubb/adapter-oas'\n * import { parserMd } from '@kubb/parser-md'\n *\n * export default defineConfig({\n *   input: { path: './petStore.yaml' },\n *   output: { path: './src/gen' },\n *   adapter: adapterOas(),\n *   parsers: [parserMd],\n *   plugins: [],\n * })\n * ```\n */\nexport const parserMd = defineParser({\n  name: 'markdown',\n  extNames: ['.md', '.markdown'],\n  print(...parts: PrintInput[]) {\n    return print(...parts)\n  },\n  parse(file) {\n    const sourceParts: string[] = []\n    for (const source of file.sources) {\n      const text = extractStringsFromNodes(source.nodes as Array<CodeNode>)\n      if (text) sourceParts.push(text.trimEnd())\n    }\n    const body = sourceParts.join('\\n\\n')\n\n    const meta = file.meta as MdMeta | undefined\n    const frontmatter = print(meta?.frontmatter ?? undefined)\n\n    const parts = [file.banner, frontmatter, body, file.footer].filter((segment): segment is string => Boolean(segment)).map((segment) => segment.trimEnd())\n    return parts.join('\\n\\n')\n  },\n})\n"],"mappings":";;;;;;;;;;;;;;;;;;AAoBA,SAAgB,iBAAiB,MAA0D;CACzF,IAAI,CAAC,QAAQ,OAAO,KAAK,KAAK,CAAC,WAAW,GAAG,OAAO;CACpD,OAAO,SAAA,GAAA,KAAA,WAAkB,KAAK,CAAC,SAAS,CAAC;;;;;;;;;;;;;AAc3C,SAAgB,MAAM,GAAG,OAAqD;CAC5E,MAAM,WAAqB,EAAE;CAC7B,KAAK,MAAM,QAAQ,OAAO;EACxB,IAAI,SAAS,QAAQ,SAAS,KAAA,KAAa,SAAS,IAAI;EACxD,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,iBAAiB,KAAK;EACrE,IAAI,MAAM,SAAS,KAAK,KAAK,SAAS,CAAC;;CAEzC,OAAO,SAAS,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;ACP9B,MAAa,YAAA,GAAA,WAAA,cAAwB;CACnC,MAAM;CACN,UAAU,CAAC,OAAO,YAAY;CAC9B,MAAM,GAAG,OAAqB;EAC5B,OAAO,MAAM,GAAG,MAAM;;CAExB,MAAM,MAAM;EACV,MAAM,cAAwB,EAAE;EAChC,KAAK,MAAM,UAAU,KAAK,SAAS;GACjC,MAAM,QAAA,GAAA,UAAA,yBAA+B,OAAO,MAAyB;GACrE,IAAI,MAAM,YAAY,KAAK,KAAK,SAAS,CAAC;;EAE5C,MAAM,OAAO,YAAY,KAAK,OAAO;EAErC,MAAM,OAAO,KAAK;EAClB,MAAM,cAAc,MAAM,MAAM,eAAe,KAAA,EAAU;EAGzD,OADc;GAAC,KAAK;GAAQ;GAAa;GAAM,KAAK;GAAO,CAAC,QAAQ,YAA+B,QAAQ,QAAQ,CAAC,CAAC,KAAK,YAAY,QAAQ,SAAS,CAC3I,CAAC,KAAK,OAAO;;CAE5B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { t as __name } from "./chunk--u3MIqq1.js";
+import * as _$_kubb_core0 from "@kubb/core";
+
+//#region src/parserMd.d.ts
+/**
+ * Metadata accepted by `parserMd`. Set `frontmatter` on a `<File meta={…}>` to
+ * have the parser prepend the corresponding YAML envelope.
+ */
+type MdMeta = {
+  frontmatter?: Record<string, unknown> | null;
+};
+/**
+ * Kubb parser for `.md` and `.markdown` files. Joins source blocks as plain
+ * markdown (separated by blank lines) and, when `file.meta.frontmatter` is set,
+ * prepends a YAML frontmatter envelope produced by `parserMd.print`.
+ *
+ * Add to the `parsers` array on `defineConfig` to opt in. `parserTs` keeps
+ * handling `.ts`/`.js` files, `parserMd` claims `.md`/`.markdown`.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { adapterOas } from '@kubb/adapter-oas'
+ * import { parserMd } from '@kubb/parser-md'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas(),
+ *   parsers: [parserMd],
+ *   plugins: [],
+ * })
+ * ```
+ */
+declare const parserMd: _$_kubb_core0.Parser<any>;
+//#endregion
+export { type MdMeta, parserMd };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,93 @@
+import "./chunk--u3MIqq1.js";
+import { extractStringsFromNodes } from "@kubb/ast";
+import { defineParser } from "@kubb/core";
+import { stringify } from "yaml";
+//#region src/utils.ts
+/**
+* Wraps a plain object as a YAML frontmatter envelope:
+*
+* ```
+* ---
+* <yaml>
+* ---
+* ```
+*
+* Returns an empty string for `null`, `undefined`, or empty objects so callers
+* can drop the result through the same filter chain as banner/footer fields.
+*/
+function printFrontmatter(data) {
+	if (!data || Object.keys(data).length === 0) return "";
+	return `---\n${stringify(data).trimEnd()}\n---`;
+}
+/**
+* Joins a list of markdown fragments with blank lines. Plain objects are
+* rendered as YAML frontmatter via {@link printFrontmatter}; strings pass
+* through unchanged.
+*
+* @example
+* ```ts
+* print({ title: 'Hi' }, '# Hello')
+* // '---\ntitle: Hi\n---\n\n# Hello'
+* ```
+*/
+function print(...parts) {
+	const rendered = [];
+	for (const part of parts) {
+		if (part === null || part === void 0 || part === "") continue;
+		const text = typeof part === "string" ? part : printFrontmatter(part);
+		if (text) rendered.push(text.trimEnd());
+	}
+	return rendered.join("\n\n");
+}
+//#endregion
+//#region src/parserMd.ts
+/**
+* Kubb parser for `.md` and `.markdown` files. Joins source blocks as plain
+* markdown (separated by blank lines) and, when `file.meta.frontmatter` is set,
+* prepends a YAML frontmatter envelope produced by `parserMd.print`.
+*
+* Add to the `parsers` array on `defineConfig` to opt in. `parserTs` keeps
+* handling `.ts`/`.js` files, `parserMd` claims `.md`/`.markdown`.
+*
+* @example
+* ```ts
+* import { defineConfig } from 'kubb'
+* import { adapterOas } from '@kubb/adapter-oas'
+* import { parserMd } from '@kubb/parser-md'
+*
+* export default defineConfig({
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   adapter: adapterOas(),
+*   parsers: [parserMd],
+*   plugins: [],
+* })
+* ```
+*/
+const parserMd = defineParser({
+	name: "markdown",
+	extNames: [".md", ".markdown"],
+	print(...parts) {
+		return print(...parts);
+	},
+	parse(file) {
+		const sourceParts = [];
+		for (const source of file.sources) {
+			const text = extractStringsFromNodes(source.nodes);
+			if (text) sourceParts.push(text.trimEnd());
+		}
+		const body = sourceParts.join("\n\n");
+		const meta = file.meta;
+		const frontmatter = print(meta?.frontmatter ?? void 0);
+		return [
+			file.banner,
+			frontmatter,
+			body,
+			file.footer
+		].filter((segment) => Boolean(segment)).map((segment) => segment.trimEnd()).join("\n\n");
+	}
+});
+//#endregion
+export { parserMd };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/utils.ts","../src/parserMd.ts"],"sourcesContent":["import { stringify } from 'yaml'\n\n/**\n * Markdown `print` input — either a markdown text fragment (passed through\n * verbatim) or a plain object that is serialised as a YAML frontmatter envelope.\n */\nexport type PrintInput = string | Record<string, unknown>\n\n/**\n * Wraps a plain object as a YAML frontmatter envelope:\n *\n * ```\n * ---\n * <yaml>\n * ---\n * ```\n *\n * Returns an empty string for `null`, `undefined`, or empty objects so callers\n * can drop the result through the same filter chain as banner/footer fields.\n */\nexport function printFrontmatter(data: Record<string, unknown> | null | undefined): string {\n  if (!data || Object.keys(data).length === 0) return ''\n  return `---\\n${stringify(data).trimEnd()}\\n---`\n}\n\n/**\n * Joins a list of markdown fragments with blank lines. Plain objects are\n * rendered as YAML frontmatter via {@link printFrontmatter}; strings pass\n * through unchanged.\n *\n * @example\n * ```ts\n * print({ title: 'Hi' }, '# Hello')\n * // '---\\ntitle: Hi\\n---\\n\\n# Hello'\n * ```\n */\nexport function print(...parts: Array<PrintInput | null | undefined>): string {\n  const rendered: string[] = []\n  for (const part of parts) {\n    if (part === null || part === undefined || part === '') continue\n    const text = typeof part === 'string' ? part : printFrontmatter(part)\n    if (text) rendered.push(text.trimEnd())\n  }\n  return rendered.join('\\n\\n')\n}\n","import type { CodeNode } from '@kubb/ast'\nimport { extractStringsFromNodes } from '@kubb/ast'\nimport { defineParser } from '@kubb/core'\nimport { print, type PrintInput } from './utils.ts'\n\n/**\n * Metadata accepted by `parserMd`. Set `frontmatter` on a `<File meta={…}>` to\n * have the parser prepend the corresponding YAML envelope.\n */\nexport type MdMeta = {\n  frontmatter?: Record<string, unknown> | null\n}\n\n/**\n * Kubb parser for `.md` and `.markdown` files. Joins source blocks as plain\n * markdown (separated by blank lines) and, when `file.meta.frontmatter` is set,\n * prepends a YAML frontmatter envelope produced by `parserMd.print`.\n *\n * Add to the `parsers` array on `defineConfig` to opt in. `parserTs` keeps\n * handling `.ts`/`.js` files, `parserMd` claims `.md`/`.markdown`.\n *\n * @example\n * ```ts\n * import { defineConfig } from 'kubb'\n * import { adapterOas } from '@kubb/adapter-oas'\n * import { parserMd } from '@kubb/parser-md'\n *\n * export default defineConfig({\n *   input: { path: './petStore.yaml' },\n *   output: { path: './src/gen' },\n *   adapter: adapterOas(),\n *   parsers: [parserMd],\n *   plugins: [],\n * })\n * ```\n */\nexport const parserMd = defineParser({\n  name: 'markdown',\n  extNames: ['.md', '.markdown'],\n  print(...parts: PrintInput[]) {\n    return print(...parts)\n  },\n  parse(file) {\n    const sourceParts: string[] = []\n    for (const source of file.sources) {\n      const text = extractStringsFromNodes(source.nodes as Array<CodeNode>)\n      if (text) sourceParts.push(text.trimEnd())\n    }\n    const body = sourceParts.join('\\n\\n')\n\n    const meta = file.meta as MdMeta | undefined\n    const frontmatter = print(meta?.frontmatter ?? undefined)\n\n    const parts = [file.banner, frontmatter, body, file.footer].filter((segment): segment is string => Boolean(segment)).map((segment) => segment.trimEnd())\n    return parts.join('\\n\\n')\n  },\n})\n"],"mappings":";;;;;;;;;;;;;;;;;AAoBA,SAAgB,iBAAiB,MAA0D;CACzF,IAAI,CAAC,QAAQ,OAAO,KAAK,KAAK,CAAC,WAAW,GAAG,OAAO;CACpD,OAAO,QAAQ,UAAU,KAAK,CAAC,SAAS,CAAC;;;;;;;;;;;;;AAc3C,SAAgB,MAAM,GAAG,OAAqD;CAC5E,MAAM,WAAqB,EAAE;CAC7B,KAAK,MAAM,QAAQ,OAAO;EACxB,IAAI,SAAS,QAAQ,SAAS,KAAA,KAAa,SAAS,IAAI;EACxD,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,iBAAiB,KAAK;EACrE,IAAI,MAAM,SAAS,KAAK,KAAK,SAAS,CAAC;;CAEzC,OAAO,SAAS,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;ACP9B,MAAa,WAAW,aAAa;CACnC,MAAM;CACN,UAAU,CAAC,OAAO,YAAY;CAC9B,MAAM,GAAG,OAAqB;EAC5B,OAAO,MAAM,GAAG,MAAM;;CAExB,MAAM,MAAM;EACV,MAAM,cAAwB,EAAE;EAChC,KAAK,MAAM,UAAU,KAAK,SAAS;GACjC,MAAM,OAAO,wBAAwB,OAAO,MAAyB;GACrE,IAAI,MAAM,YAAY,KAAK,KAAK,SAAS,CAAC;;EAE5C,MAAM,OAAO,YAAY,KAAK,OAAO;EAErC,MAAM,OAAO,KAAK;EAClB,MAAM,cAAc,MAAM,MAAM,eAAe,KAAA,EAAU;EAGzD,OADc;GAAC,KAAK;GAAQ;GAAa;GAAM,KAAK;GAAO,CAAC,QAAQ,YAA+B,QAAQ,QAAQ,CAAC,CAAC,KAAK,YAAY,QAAQ,SAAS,CAC3I,CAAC,KAAK,OAAO;;CAE5B,CAAC"}

package/extension.yaml

@@ -0,0 +1,74 @@
+$schema: https://kubb.dev/schemas/extension.json
+kind: parser
+id: parser-md
+name: Markdown
+description: Markdown file parser for Kubb. Joins source blocks as plain markdown and renders YAML frontmatter via `parserMd.print`.
+category: docs
+type: official
+npmPackage: '@kubb/parser-md'
+docsPath: /parsers/parser-md
+repo: https://github.com/kubb-labs/kubb
+maintainers:
+  - name: Stijn Van Hulle
+    github: stijnvanhulle
+compatibility:
+  kubb: '>=5.0.0'
+  node: '>=22'
+tags:
+  - markdown
+  - frontmatter
+  - parser
+  - docs
+  - yaml
+resources:
+  documentation: https://kubb.dev/parsers/parser-md
+  repository: https://github.com/kubb-labs/kubb
+  issues: https://github.com/kubb-labs/kubb/issues
+  changelog: https://github.com/kubb-labs/kubb/blob/main/packages/parser-md/CHANGELOG.md
+featured: false
+intro: |-
+  `@kubb/parser-md` emits `.md` and `.markdown` files. Source blocks pass through as plain markdown, joined by blank lines. Call `parserMd.print` on the parser instance to convert a metadata object into a YAML frontmatter envelope (`---\n…\n---`).
+
+  Use it when a plugin needs to generate documentation alongside the TypeScript output — README sections, changelog excerpts, MDX-flavoured pages — without hand-rolling a frontmatter string builder.
+
+  Configure on `defineConfig({ parsers: [parserMd] })`. The parser claims `.md` and `.markdown`; pair it with `parserTs` so the same generator can emit both `.ts` and `.md` files in a single run.
+examples:
+  - name: Standalone markdown
+    files:
+      - name: kubb.config.ts
+        lang: typescript
+        twoslash: false
+        code: |-
+          import { defineConfig } from 'kubb'
+          import { adapterOas } from '@kubb/adapter-oas'
+          import { parserMd } from '@kubb/parser-md'
+
+          export default defineConfig({
+            input: { path: './petStore.yaml' },
+            output: { path: './src/gen' },
+            adapter: adapterOas(),
+            parsers: [parserMd],
+            plugins: [],
+          })
+  - name: Markdown alongside TypeScript
+    files:
+      - name: kubb.config.ts
+        lang: typescript
+        twoslash: false
+        code: |-
+          import { defineConfig } from 'kubb'
+          import { adapterOas } from '@kubb/adapter-oas'
+          import { parserMd } from '@kubb/parser-md'
+          import { parserTs } from '@kubb/parser-ts'
+
+          export default defineConfig({
+            input: { path: './petStore.yaml' },
+            output: { path: './src/gen' },
+            adapter: adapterOas(),
+            parsers: [parserTs, parserMd],
+            plugins: [],
+          })
+notes:
+  - type: tip
+    body: |-
+      `parserMd.print({ title: 'Pets', layout: 'doc' })` returns `---\ntitle: Pets\nlayout: doc\n---`. Render it from a plugin to inject frontmatter into a generated page without depending on `yaml` directly.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@kubb/parser-md",
+  "version": "5.0.0-beta.25",
+  "description": "Markdown source file parser for Kubb. Converts the universal AST to `.md` source and renders YAML frontmatter via the `print` helper.",
+  "keywords": [
+    "codegen",
+    "frontmatter",
+    "kubb",
+    "markdown",
+    "parser",
+    "yaml"
+  ],
+  "license": "MIT",
+  "author": "stijnvanhulle",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kubb-labs/kubb.git",
+    "directory": "packages/parser-md"
+  },
+  "files": [
+    "src",
+    "dist",
+    "extension.yaml",
+    "!/**/**.test.**",
+    "!/**/__tests__/**",
+    "!/**/__snapshots__/**"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "npx rimraf ./dist",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "release": "pnpm publish --no-git-check",
+    "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
+    "start": "tsdown --watch",
+    "test": "vitest --passWithNoTests",
+    "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"
+  },
+  "dependencies": {
+    "@kubb/ast": "workspace:*",
+    "@kubb/core": "workspace:*",
+    "yaml": "catalog:"
+  },
+  "devDependencies": {
+    "@internals/utils": "workspace:*"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { parserMd, type MdMeta } from './parserMd.ts'

package/src/parserMd.ts

@@ -0,0 +1,57 @@
+import type { CodeNode } from '@kubb/ast'
+import { extractStringsFromNodes } from '@kubb/ast'
+import { defineParser } from '@kubb/core'
+import { print, type PrintInput } from './utils.ts'
+
+/**
+ * Metadata accepted by `parserMd`. Set `frontmatter` on a `<File meta={…}>` to
+ * have the parser prepend the corresponding YAML envelope.
+ */
+export type MdMeta = {
+  frontmatter?: Record<string, unknown> | null
+}
+
+/**
+ * Kubb parser for `.md` and `.markdown` files. Joins source blocks as plain
+ * markdown (separated by blank lines) and, when `file.meta.frontmatter` is set,
+ * prepends a YAML frontmatter envelope produced by `parserMd.print`.
+ *
+ * Add to the `parsers` array on `defineConfig` to opt in. `parserTs` keeps
+ * handling `.ts`/`.js` files, `parserMd` claims `.md`/`.markdown`.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { adapterOas } from '@kubb/adapter-oas'
+ * import { parserMd } from '@kubb/parser-md'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas(),
+ *   parsers: [parserMd],
+ *   plugins: [],
+ * })
+ * ```
+ */
+export const parserMd = defineParser({
+  name: 'markdown',
+  extNames: ['.md', '.markdown'],
+  print(...parts: PrintInput[]) {
+    return print(...parts)
+  },
+  parse(file) {
+    const sourceParts: string[] = []
+    for (const source of file.sources) {
+      const text = extractStringsFromNodes(source.nodes as Array<CodeNode>)
+      if (text) sourceParts.push(text.trimEnd())
+    }
+    const body = sourceParts.join('\n\n')
+
+    const meta = file.meta as MdMeta | undefined
+    const frontmatter = print(meta?.frontmatter ?? undefined)
+
+    const parts = [file.banner, frontmatter, body, file.footer].filter((segment): segment is string => Boolean(segment)).map((segment) => segment.trimEnd())
+    return parts.join('\n\n')
+  },
+})

package/src/utils.ts

@@ -0,0 +1,45 @@
+import { stringify } from 'yaml'
+
+/**
+ * Markdown `print` input — either a markdown text fragment (passed through
+ * verbatim) or a plain object that is serialised as a YAML frontmatter envelope.
+ */
+export type PrintInput = string | Record<string, unknown>
+
+/**
+ * Wraps a plain object as a YAML frontmatter envelope:
+ *
+ * ```
+ * ---
+ * <yaml>
+ * ---
+ * ```
+ *
+ * Returns an empty string for `null`, `undefined`, or empty objects so callers
+ * can drop the result through the same filter chain as banner/footer fields.
+ */
+export function printFrontmatter(data: Record<string, unknown> | null | undefined): string {
+  if (!data || Object.keys(data).length === 0) return ''
+  return `---\n${stringify(data).trimEnd()}\n---`
+}
+
+/**
+ * Joins a list of markdown fragments with blank lines. Plain objects are
+ * rendered as YAML frontmatter via {@link printFrontmatter}; strings pass
+ * through unchanged.
+ *
+ * @example
+ * ```ts
+ * print({ title: 'Hi' }, '# Hello')
+ * // '---\ntitle: Hi\n---\n\n# Hello'
+ * ```
+ */
+export function print(...parts: Array<PrintInput | null | undefined>): string {
+  const rendered: string[] = []
+  for (const part of parts) {
+    if (part === null || part === undefined || part === '') continue
+    const text = typeof part === 'string' ? part : printFrontmatter(part)
+    if (text) rendered.push(text.trimEnd())
+  }
+  return rendered.join('\n\n')
+}