namespace
Markdown related APIs.
Provides fast markdown parsing and rendering with three output modes:
html() — render to an HTML stringrender() — render with custom callbacks for each elementreact() — parse to React-compatible JSX elementsSupports 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**");
// "<h1>Hello <strong>world</strong></h1>\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.
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 });
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 } }
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 the GFM tag filter, which replaces < with < for disallowed HTML tags (e.g. <script>, <style>, <iframe>). Default: false.
Enable underline syntax (__text__ renders as <u> instead of <strong>). Default: false.
Options for react() — parser options and element symbol configuration.
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 } }
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 } }
Which $$typeof symbol to use on the generated elements.
19 (default): Symbol.for('react.transitional.element')18: Symbol.for('react.element') — use this for React 18 and olderEnable the GFM tag filter, which replaces < with < for disallowed HTML tags (e.g. <script>, <style>, <iframe>). Default: false.
Enable underline syntax (__text__ renders as <u> instead of <strong>). Default: false.
Code block. meta.language is the info-string (e.g. "js"). Only passed for fenced code blocks with a language.
Heading (level 1–6). id is set when headings: { ids: true } is enabled.
List item. meta always includes {index, depth, ordered}. meta.start is set for ordered lists; meta.checked is set for task list items.
A component that accepts props P: a function, class, or HTML tag name.
Render markdown to an ANSI-colored terminal string.
Supports headings, lists, tables, inline styles, syntax-highlighted code blocks, links, images, and blockquotes. By default, enables all GFM extensions plus wikilinks, underline, and LaTeX math.
The markdown string or buffer to render
Optional theme overrides
An ANSI-colored string
const out = Bun.markdown.ansi("# Hello\n\n**bold** and *italic*\n");
process.stdout.write(out);
// Plain text, no escape codes
const plain = Bun.markdown.ansi("# Hello", { colors: false });
// Enable clickable OSC 8 hyperlinks
const linked = Bun.markdown.ansi("[docs](https://bun.com)", {
hyperlinks: true,
});
// Inline images via Kitty Graphics Protocol
const withImg = Bun.markdown.ansi("", {
kittyGraphics: true,
});
// Custom width
const wrapped = Bun.markdown.ansi(longText, { columns: 60 });
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**");
// "<h1>Hello <strong>world</strong></h1>\n"
// With options
const html = Bun.markdown.html("## Hello", { headings: { ids: true } });
// '<h2 id="hello">Hello</h2>\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 }) => `<h${level} class="title">${children}</h${level}>`,
paragraph: (children) => `<p>${children}</p>`,
strong: (children) => `<b>${children}</b>`,
});
// 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 });