Bun.markdown object | API Reference | Bun

Markdown related APIs.

Provides fast markdown parsing and rendering with three output modes:

Supports GFM extensions (tables, strikethrough, task lists, autolinks) and component overrides to replace default HTML tags with custom components.

// Render markdown to HTML
const html = Bun.markdown.html("# Hello **world**");
// "Hello world\n"

// Render with custom callbacks
const ansi = Bun.markdown.render("# Hello **world**", {
heading: (children, { level }) => `\x1b[1m${children}\x1b[0m\n`,
strong: (children) => `\x1b[1m${children}\x1b[22m`,
paragraph: (children) => children + "\n",
});

// Render as a React component
function Markdown({ text }: { text: string }) {
return Bun.markdown.react(text);
}

// With component overrides
const element = Bun.markdown.react("# Hello", { h1: MyHeadingComponent });

Theme for ANSI terminal rendering.

Emit ANSI color + styling escape sequences. When false, the renderer falls back to plain ASCII chrome (no box drawing, no emoji, no escape codes).

Line width used for word-wrapping paragraphs and headings and for the horizontal rule. Pass 0 to disable wrapping.

Emit OSC 8 hyperlinks (clickable links in modern terminals). When false, links render as text (url).

Inline images using the Kitty Graphics Protocol when the src resolves to a local file on disk. Falls through to the text alt for remote URLs. Supported by Kitty, WezTerm, and Ghostty.

True when the terminal background is light. Affects the color palette chosen for inline code backgrounds. Defaults to detecting from the COLORFGBG environment variable.

Meta passed to th and td callbacks.

Column alignment.

Column alignment.

Meta passed to the code callback.

The info-string language (e.g. "js").

The info-string language (e.g. "js").

Component overrides for react().

Replace default HTML tags with custom React components. Each override receives the same props the default element would get.

function Code({ language, children }: { language?: string; children: React.ReactNode }) {
return pre data-language={language}>code>{children}code>pre>;
}
Bun.markdown.react(text, { pre: Code });

Meta passed to the heading callback.

Heading ID slug. Set when headings: { ids: true } is enabled.

Heading level (1–6).

Heading ID slug. Set when headings: { ids: true } is enabled.

Meta passed to the image callback.

Image URL.

Image title attribute.

Alt text.

Image URL.

Image title attribute.

Meta passed to the link callback.

Link URL.

Link title attribute.

Link URL.

Link title attribute.

Meta passed to the listItem callback.

Task list checked state. Set for - [x] / - [ ] items.

Nesting depth of the parent list. 0 for items in a top-level list.

0-based index of this item within its parent list.

Whether the parent list is ordered.

The start number of the parent list (only set when ordered is true).

Task list checked state. Set for - [x] / - [ ] items.

Meta passed to the list callback.

Nesting depth. 0 for a top-level list, 1 for a list inside a list item, etc.

Whether this is an ordered list.

The start number for ordered lists.

Options for configuring the markdown parser.

By default, GFM extensions (tables, strikethrough, task lists) are enabled.

Enable autolinks. Pass true to enable all autolink types (URL, WWW, email), or an object to enable individually.

// Enable all autolinks
{ autolinks: true }
// Enable only URL and email autolinks
{ autolinks: { url: true, email: true } }

Collapse whitespace in text content. Default: false.

Treat soft line breaks as hard line breaks. Default: false.

Configure heading IDs and autolink headings. Pass true to enable both heading IDs and autolink headings, or an object to configure individually.

// Enable both heading IDs and autolink headings
{ headings: true }
// Enable only heading IDs
{ headings: { ids: true } }

Enable LaTeX math ($inline$ and $$display$$). Default: false.

Disable HTML blocks. Default: false.

Disable inline HTML spans. Default: false.

Disable indented code blocks. Default: false.

Allow ATX headers without a space after #. Default: false.

Enable GFM strikethrough (~~text~~). Default: true.

Enable GFM tables. Default: true.

Collapse whitespace in text content. Default: false.

Treat soft line breaks as hard line breaks. Default: false.

Configure heading IDs and autolink headings. Pass true to enable both heading IDs and autolink headings, or an object to configure individually.

// Enable both heading IDs and autolink headings
{ headings: true }
// Enable only heading IDs
{ headings: { ids: true } }

Enable LaTeX math ($inline$ and $$display$$). Default: false.

Disable HTML blocks. Default: false.

Disable inline HTML spans. Default: false.

Disable indented code blocks. Default: false.

Allow ATX headers without a space after #. Default: false.

Which $$typeof symbol to use on the generated elements.

Enable GFM strikethrough (~~text~~). Default: true.

Enable GFM tables. Default: true.

Render markdown to an HTML string.

The markdown string or buffer to render

Parser options

An HTML string

const html = Bun.markdown.html("# Hello **world**");
// "Hello world\n"

// With options
const html = Bun.markdown.html("## Hello", { headings: { ids: true } });
// 'Hello\n'

Render markdown to React JSX elements.

Returns a React Fragment containing the parsed markdown as children. Can be returned directly from a component or passed to renderToString().

Override any HTML element with a custom component by passing it in the second argument, keyed by tag name. Custom components receive the same props the default elements would (e.g. href for links, language for code blocks).

Parser options (including reactVersion) are passed as a separate third argument. Uses Symbol.for('react.transitional.element') by default (React 19). Pass reactVersion: 18 for React 18 and older.

The markdown string or buffer to parse

Component overrides keyed by HTML tag name

Parser options and element symbol configuration

A React Fragment element containing the parsed markdown

// Use directly as a component return value
function Markdown({ text }: { text: string }) {
return Bun.markdown.react(text);
}

// Server-side rendering
import { renderToString } from "react-dom/server";
const html = renderToString(Bun.markdown.react("# Hello **world**"));

// Custom components receive element props
function Code({ language, children }: { language?: string; children: React.ReactNode }) {
return pre data-language={language}>code>{children}code>pre>;
}
function Link({ href, children }: { href: string; children: React.ReactNode }) {
return a href={href} target="_blank">{children}a>;
}
const el = Bun.markdown.react(text, { pre: Code, a: Link });

// For React 18 and older
const el18 = Bun.markdown.react(text, undefined, { reactVersion: 18 });

Render markdown with custom JavaScript callbacks for each element.

Each callback receives the accumulated children as a string and optional metadata, and returns a string. Return null or undefined to omit an element. If no callback is registered, children pass through unchanged.

Parser options are passed as a separate third argument.

The markdown string to render

Callbacks for each element type

Parser options

The accumulated string output

// Custom HTML with classes
const html = Bun.markdown.render("# Title\n\nHello **world**", {
heading: (children, { level }) => `${level} class="title">${children}${level}>`,
paragraph: (children) => `
${children}
`,
strong: (children) => `${children}`,
});

// ANSI terminal output
const ansi = Bun.markdown.render("# Hello\n\n**bold**", {
heading: (children) => `\x1b[1;4m${children}\x1b[0m\n`,
paragraph: (children) => children + "\n",
strong: (children) => `\x1b[1m${children}\x1b[22m`,
});

// With parser options as third argument
const text = Bun.markdown.render("Visit www.example.com", {
link: (children, { href }) => `[${children}](${href})`,
paragraph: (children) => children,
}, { autolinks: true });