@kubb/parser-md lets Kubb emit .md and .markdown files. Any plugin that writes a markdown source has its output serialized for you.

The parser joins a file's source blocks with blank lines to form the body. When file.meta.frontmatter is set, it renders those keys as a YAML frontmatter block and prepends it, so you do not add a yaml dependency yourself.

TIP

parserMd ships with Kubb and runs by default next to parserTs and parserTsx. Add it to parsers yourself only when you set a custom list, since a custom parsers array replaces the whole default set. Files whose extension has no registered parser are written by joining their sources verbatim.

Installation

bun

bun add -d @kubb/parser-md@beta

pnpm

pnpm add -D @kubb/parser-md@beta

npm

npm install --save-dev @kubb/parser-md@beta

yarn

yarn add -D @kubb/parser-md@beta

Frontmatter

@kubb/parser-md takes no options of its own. To add a YAML frontmatter block to a generated page, set frontmatter on a file's meta inside a plugin. The parser renders those keys and prepends them to the output. Any serializable object works.

Type:	Record<string, unknown> | null

Plugin that sets frontmatter

ast.factory.createFile({
  baseName: 'README.md',
  path: `${config.output.path}/README.md`,
  meta: {
    frontmatter: { title: 'API Reference', layout: 'doc' },
  },
  sources: [...],
})

The parser turns that meta into:

---
title: API Reference
layout: doc
---

You can also call parserMd.print directly to build a frontmatter envelope. It accepts objects and markdown strings and joins them with blank lines, so parserMd.print({ title: 'Pets', layout: 'doc' }) returns ---\ntitle: Pets\nlayout: doc\n---.

Example

Standalone markdown

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: [],
})

Markdown alongside TypeScript

import {  } from 'kubb'
import {  } from '@kubb/adapter-oas'
import {  } from '@kubb/parser-md'
import { ,  } from '@kubb/parser-ts'

export default ({
  : { : './petStore.yaml' },
  : { : './src/gen' },
  : (),
  : [, , ],
  : [],
})

See also

• Changelog