Markdown

不稳定的 API — 此 API 正在积极开发中，可能在未来的 Bun 版本中发生变化。

Bun 包含一个用 Rust 编写的快速内置 Markdown 解析器。它支持 GitHub Flavored Markdown（GFM）扩展，并提供三个 API：

Bun.markdown.html() — 将 Markdown 渲染为 HTML 字符串
Bun.markdown.render() — 使用每个元素的自定义回调渲染 Markdown
Bun.markdown.react() — 将 Markdown 渲染为 React JSX 元素

`Bun.markdown.html()`

将 Markdown 字符串转换为 HTML。

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

GFM 扩展（如表格、删除线和任务列表）默认启用：

const html = Bun.markdown.html(`
| Feature      | Status |
|-------------|--------|
| Tables       | ~~done~~ |
| Strikethrough| ~~done~~ |
| Task lists   | done |
`);

选项

传递一个选项对象作为第二个参数来配置解析器：

const html = Bun.markdown.html("some markdown", {
  tables: true, // GFM 表格（默认：true）
  strikethrough: true, // GFM 删除线（默认：true）
  tasklists: true, // GFM 任务列表（默认：true）
  tagFilter: true, // GFM 标签过滤器，用于不允许的 HTML 标签
  autolinks: true, // 自动链接 URL、电子邮件和 www. 链接
});

所有可用选项：

选项	默认值	说明
`tables`	`true`	GFM 表格
`strikethrough`	`true`	GFM 删除线（`~~text~~`）
`tasklists`	`true`	GFM 任务列表（`- [x] item`）
`autolinks`	`false`	启用自动链接 — 参见自动链接
`headings`	`false`	标题 ID 和自动链接 — 参见标题 ID
`hardSoftBreaks`	`false`	将软换行视为硬换行
`wikiLinks`	`false`	启用 `[[wiki links]]`
`underline`	`false`	`__text__` 渲染为 `<u>` 而不是 `<strong>`
`latexMath`	`false`	启用 $inline$ 和 `$$display$$` 数学公式
`collapseWhitespace`	`false`	折叠文本中的空白
`permissiveAtxHeaders`	`false`	ATX 标题在 `#` 后可以不跟空格
`noIndentedCodeBlocks`	`false`	禁用缩进代码块
`noHtmlBlocks`	`false`	禁用 HTML 块
`noHtmlSpans`	`false`	禁用内联 HTML
`tagFilter`	`false`	GFM 标签过滤器，用于不允许的 HTML 标签

自动链接

传递 true 以启用所有自动链接类型，或传递一个对象以实现精细控制：

// 启用所有自动链接（URL、WWW、电子邮件）
Bun.markdown.html("Visit www.example.com", { autolinks: true });

// 仅启用特定类型
Bun.markdown.html("Visit www.example.com", {
  autolinks: { url: true, www: true },
});

标题 ID

传递 true 以同时启用标题 ID 和自动链接标题，或传递一个对象以实现精细控制：

// 启用标题 ID 和自动链接标题
Bun.markdown.html("## Hello World", { headings: true });
// '<h2 id="hello-world"><a href="#hello-world">Hello World</a></h2>\n'

// 仅启用标题 ID（无自动链接）
Bun.markdown.html("## Hello World", { headings: { ids: true } });
// '<h2 id="hello-world">Hello World</h2>\n'

`Bun.markdown.render()`

解析 Markdown 并使用自定义 JavaScript 回调进行渲染。这使您可以完全控制输出格式 — 您可以生成带有自定义类名的 HTML、React 元素、ANSI 终端输出或任何其他字符串格式。

const result = Bun.markdown.render("# Hello **world**", {
  heading: (children, { level }) => `<h${level} class="title">${children}</h${level}>`,
  strong: children => `<b>${children}</b>`,
  paragraph: children => `<p>${children}</p>`,
});
// '<h1 class="title">Hello <b>world</b></h1>'

回调签名

每个回调接收：

children — 元素的累积内容，作为字符串
meta（可选）— 一个包含元素特定元数据的对象

返回一个字符串以替换元素的渲染。返回 null 或 undefined 以完全从输出中省略该元素。如果没有为元素注册回调，其子元素会原样传递。

块级回调

回调	元数据	说明
`heading`	`{ level, id? }`	标题级别 1–6。启用 `headings: { ids: true }` 时设置 `id`
`paragraph`	—	段落块
`blockquote`	—	引用块
`code`	`{ language? }`	围栏或缩进的代码块。`language` 是在围栏上指定时的信息字符串
`list`	`{ ordered, start?, depth }`	`depth` 是嵌套级别（0 = 顶层）。有序列表时设置 `start`
`listItem`	`{ index, depth, ordered, start?, checked? }`	参见下方的列表项元数据
`hr`	—	水平线
`table`	—	表格块
`thead`	—	表格头
`tbody`	—	表格体
`tr`	—	表格行
`th`	`{ align? }`	表头单元格。`align` 为 `"left"`、`"center"`、`"right"` 或缺失
`td`	`{ align? }`	表数据单元格
`html`	—	原始 HTML 内容

列表项元数据

listItem 回调接收直接渲染标记所需的一切：

index — 在父列表中的从 0 开始的位置
depth — 父列表的嵌套级别（0 = 顶层）
ordered — 父列表是否是有序的
start — 父列表的起始编号（仅当 ordered 为 true 时）
checked — 任务列表状态（仅对 - [x] / - [ ] 项）

内联回调

回调	元数据	说明
`strong`	—	强调（`text`）
`emphasis`	—	斜体（`text`）
`link`	`{ href: string, title?: string }`	链接
`image`	`{ src: string, title?: string }`	图片
`codespan`	—	内联代码（`code`）
`strikethrough`	—	删除线（`~~text~~`）
`text`	—	纯文本内容

示例

带类名的自定义 HTML

const html = Bun.markdown.render("# Title\n\nHello **world**", {
  heading: (children, { level }) => `<h${level} class="heading heading-${level}">${children}</h${level}>`,
  paragraph: children => `<p class="body">${children}</p>`,
  strong: children => `<strong class="bold">${children}</strong>`,
});

去除所有格式

const plaintext = Bun.markdown.render("# Hello **world**", {
  heading: children => children,
  paragraph: children => children,
  strong: children => children,
  emphasis: children => children,
  link: children => children,
  image: () => "",
  code: children => children,
  codespan: children => children,
});
// "Hello world"

省略元素

返回 null 或 undefined 以从输出中移除元素：

const result = Bun.markdown.render("# Title\n\n![logo](img.png)\n\nHello", {
  image: () => null, // 移除所有图片
  heading: children => children,
  paragraph: children => children + "\n",
});
// "Title\nHello\n"

ANSI 终端输出

const ansi = Bun.markdown.render("# Hello\n\nThis is **bold** and *italic*", {
  heading: (children, { level }) => `\x1b[1;4m${children}\x1b[0m\n`,
  paragraph: children => children + "\n",
  strong: children => `\x1b[1m${children}\x1b[22m`,
  emphasis: children => `\x1b[3m${children}\x1b[23m`,
});

嵌套列表编号

listItem 回调接收直接渲染标记所需的一切 — 无需后处理：

const result = Bun.markdown.render("1. first\n   1. sub-a\n   2. sub-b\n2. second", {
  listItem: (children, { index, depth, ordered, start }) => {
    const n = (start ?? 1) + index;
    // depth 0 为 1. 2. 3.，depth 1 为 a. b. c.，depth 2 为 i. ii. iii.
    const marker = !ordered
      ? "-"
      : depth === 0
        ? `${n}.`
        : depth === 1
          ? `${String.fromCharCode(96 + n)}.`
          : `${toRoman(n)}.`;
    return "  ".repeat(depth) + marker + " " + children.trimEnd() + "\n";
  },
  // 在新行前添加，以便嵌套列表与父项文本分开
  list: children => "\n" + children,
});
// 1. first
//   a. sub-a
//   b. sub-b
// 2. second

代码块语法高亮

const result = Bun.markdown.render("```js\nconsole.log('hi')\n```", {
  code: (children, meta) => {
    const lang = meta?.language ?? "";
    return `<pre><code class="language-${lang}">${children}</code></pre>`;
  },
});

解析器选项

将解析器选项作为单独的第三个参数传递：

const result = Bun.markdown.render(
  "Visit www.example.com",
  {
    link: (children, { href }) => `[${children}](${href})`,
    paragraph: children => children,
  },
  { autolinks: true },
);

`Bun.markdown.react()`

直接将 Markdown 渲染为 React 元素。返回一个可以用作组件返回值的 <Fragment>。

function Markdown({ text }: { text: string }) {
  return Bun.markdown.react(text);
}

服务端渲染

适用于 renderToString() 和 React Server Components：

import { renderToString } from "react-dom/server";

const html = renderToString(Bun.markdown.react("# Hello **world**"));
// "<h1>Hello <strong>world</strong></h1>"

组件覆盖

通过在第二个参数中按键名传递自定义 React 组件来替换任何 HTML 元素：

function Code({ language, children }) {
  return (
    <pre data-language={language}>
      <code>{children}</code>
    </pre>
  );
}

function Link({ href, title, children }) {
  return (
    <a href={href} title={title} target="_blank" rel="noopener noreferrer">
      {children}
    </a>
  );
}

function Heading({ id, children }) {
  return (
    <h2 id={id}>
      <a href={`#${id}`}>{children}</a>
    </h2>
  );
}

const el = Bun.markdown.react(
  content,
  {
    pre: Code,
    a: Link,
    h2: Heading,
  },
  { headings: { ids: true } },
);

可用覆盖

解析器生成的每个 HTML 标签都可以覆盖：

选项	属性	说明
`h1`–`h6`	`{ id?, children }`	标题。启用 `headings: { ids: true }` 时设置 `id`
`p`	`{ children }`	段落
`blockquote`	`{ children }`	引用
`pre`	`{ language?, children }`	代码块。`language` 是信息字符串（例如 `"js"`）
`hr`	`{}`	水平线（无子元素）
`ul`	`{ children }`	无序列表
`ol`	`{ start, children }`	有序列表。`start` 是第一项编号
`li`	`{ checked?, children }`	列表项。任务列表项时设置 `checked`
`table`	`{ children }`	表格
`thead`	`{ children }`	表格头
`tbody`	`{ children }`	表格体
`tr`	`{ children }`	表格行
`th`	`{ align?, children }`	表头单元格
`td`	`{ align?, children }`	表数据单元格
`em`	`{ children }`	斜体（`text`）
`strong`	`{ children }`	加粗（`text`）
`a`	`{ href, title?, children }`	链接
`img`	`{ src, alt?, title? }`	图片（无子元素）
`code`	`{ children }`	内联代码
`del`	`{ children }`	删除线（`~~text~~`）
`br`	`{}`	硬换行（无子元素）

React 18 及更早版本

默认情况下，元素使用 Symbol.for('react.transitional.element') 作为 $$typeof 符号。对于 React 18 及更早版本，在选项（第三个参数）中传递 reactVersion: 18：

function Markdown({ text }: { text: string }) {
  return Bun.markdown.react(text, undefined, { reactVersion: 18 });
}

解析器选项

将任意解析器选项作为第三个参数传递：

const el = Bun.markdown.react("## Hello World", undefined, {
  headings: { ids: true },
  autolinks: true,
});

开始入门

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

互操作与工具

实用工具

标准与兼容性

贡献指南

`Bun.markdown.html()`

选项

自动链接

标题 ID

`Bun.markdown.render()`

回调签名

块级回调

列表项元数据

内联回调

示例

带类名的自定义 HTML

去除所有格式

省略元素

ANSI 终端输出

嵌套列表编号

代码块语法高亮

解析器选项

`Bun.markdown.react()`

服务端渲染

组件覆盖

可用覆盖

React 18 及更早版本

解析器选项

​Bun.markdown.html()

​选项

​自动链接

​标题 ID

​Bun.markdown.render()

​回调签名

​块级回调

​列表项元数据

​内联回调

​示例

​带类名的自定义 HTML

​去除所有格式

​省略元素

​ANSI 终端输出

​嵌套列表编号

​代码块语法高亮

​解析器选项

​Bun.markdown.react()

​服务端渲染

​组件覆盖

​可用覆盖

​React 18 及更早版本

​解析器选项

`Bun.markdown.html()`

选项

自动链接

标题 ID

`Bun.markdown.render()`

回调签名

块级回调

列表项元数据

内联回调

示例

带类名的自定义 HTML

去除所有格式

省略元素

ANSI 终端输出

嵌套列表编号

代码块语法高亮

解析器选项

`Bun.markdown.react()`

服务端渲染

组件覆盖

可用覆盖

React 18 及更早版本

解析器选项