Open Studio
Officialv5.4.1MITkubb >=5.0.0node >=22

@kubb/parser-md

Emits `.md` and `.markdown` files from the Kubb AST, joining source blocks as plain markdown and prepending YAML frontmatter from a file's meta.

markdownfrontmatterparserdocsyaml
Stijn Van Hulle

Stijn Van Hulle

@stijnvanhulle

Downloads
106k/ mo
Stars
1.8k
Bundle size
22.5 kB
Updated
today

@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, and prepends a YAML frontmatter block when file.meta.frontmatter is set, so you never add a yaml dependency yourself.

Tip

parserMd runs by default next to parserTs and parserTsx. Add it back to a custom parsers list when you override the defaults, 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 ​

shell
bun add -d @kubb/parser-md
shell
pnpm add -D @kubb/parser-md
shell
npm install --save-dev @kubb/parser-md
shell
yarn add -D @kubb/parser-md

Dependencies ​

@kubb/parser-md has no plugin dependencies. It is a standalone parser you register on defineConfig's parsers array, and needs no other Kubb plugin.

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
typescript
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:

markdown
---
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 ​

typescript
import { defineConfig } from 'kubb'
import { adapterOas } from '@kubb/adapter-oas'
import { parserMd } from '@kubb/parser-md'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen' },
  adapter: adapterOas(),
  parsers: [parserMd()],
  plugins: [],
})
typescript
import { defineConfig } from 'kubb'
import { adapterOas } from '@kubb/adapter-oas'
import { parserMd } from '@kubb/parser-md'
import { parserTs, parserTsx } from '@kubb/parser-ts'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen' },
  adapter: adapterOas(),
  parsers: [parserTs(), parserTsx(), parserMd()],
  plugins: [],
})

See also ​

Options