sosukesuzuki · Sep 5, 2026 · Sep 5, 2026 · Sep 6, 2026 · Sep 6, 2026 · Sep 6, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -364,6 +364,7 @@ thiserror = "2"
 smallvec = "1"
 itoa = "1"
 encoding_rs = "0.8.35"
+typed-arena = "2"
 # Vendored, not crates.io — see the `exclude = ["vendor"]` note above.
 lol_html = { path = "vendor/lolhtml" }
 bun_opaque = { path = "src/opaque" }

diff --git a/bench/bun.lock b/bench/bun.lock
diff --git a/bench/package.json b/bench/package.json
@@ -27,6 +27,8 @@
     "strip-ansi": "^7.1.0",
     "tar": "^7.4.3",
     "tinycolor2": "^1.6.0",
+    "turndown": "^7.2.4",
+    "turndown-plugin-gfm": "^1.0.2",
     "wrap-ansi": "^9.0.0",
     "zx": "^7.2.3"
   },

diff --git a/bench/snippets/html-to-markdown.mjs b/bench/snippets/html-to-markdown.mjs
@@ -0,0 +1,95 @@
+// HTML → Markdown: Bun.markdown.fromHTML vs turndown (+ turndown-plugin-gfm).
+//
+//   bun bench/snippets/html-to-markdown.mjs            # synthetic pages
+//   bun bench/snippets/html-to-markdown.mjs page.html  # your own saved pages
+//
+// turndown is what most JS apps use for this today; it builds a DOM with a
+// pure-JS HTML parser (domino) and walks it with regex-heavy rules, so large
+// pages cost hundreds of milliseconds of main-thread time and a lot of
+// transient garbage. The synthetic input below is shaped like a docs/article
+// page (nav, prose with inline markup, code blocks, tables, lists) and is
+// repeated to reach the sizes real pages have.
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import TurndownService from "turndown";
+import { gfm } from "turndown-plugin-gfm";
+import { bench, group, run } from "../runner.mjs";
+
+const td = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced", bulletListMarker: "-", hr: "---" });
+td.use(gfm);
+td.remove(["script", "style"]);
+
+const section = i => `
+<section id="s${i}">
+  <h2 class="heading"><a href="#s${i}">Section ${i}: configuring the <code>thing</code></a></h2>
+  <p>
+    Lorem ipsum <strong>dolor sit amet</strong>, consectetur <em>adipiscing</em> elit. Use
+    <a href="/docs/api/thing?id=${i}" title="API reference">the <code>thing()</code> API</a> to
+    frobnicate the widget &mdash; it&rsquo;s <del>slow</del> fast now. See issue
+    <a href="https://example.com/issues/${1000 + i}">#${1000 + i}</a> for details, and note that
+    2 * 3 = 6 and snake_case_names are left alone.
+  </p>
+  <div class="highlight highlight-source-ts"><pre><code class="language-ts">import { thing } from "pkg";
+
+export async function run${i}(input: string): Promise&lt;number&gt; {
+  const result = await thing(input, { retries: ${i % 5}, verbose: true });
+  if (!result.ok) throw new Error(\`failed: \${result.error}\`);
+  return result.value * 2;
+}
+</code></pre></div>
+  <table class="params">
+    <thead><tr><th>Option</th><th align="center">Type</th><th align="right">Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td><code>retries</code></td><td><code>number</code></td><td>3</td><td>How many times to retry before giving up.</td></tr>
+      <tr><td><code>verbose</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Log each attempt to <code>stderr</code>.</td></tr>
+      <tr><td><code>signal</code></td><td><code>AbortSignal</code></td><td>&mdash;</td><td>Cancels the <em>in-flight</em> attempt | and any pending retries.</td></tr>
+    </tbody>
+  </table>
+  <ul>
+    <li>First point with <b>bold</b> and a <a href="/x/${i}">link</a></li>
+    <li>Second point
+      <ol start="3"><li>nested three</li><li>nested four<ul><li>deeper</li></ul></li></ol>
+    </li>
+    <li><input type="checkbox" checked> done item</li>
+    <li><p>Loose item with a paragraph.</p><blockquote><p>And a quote<br>with a break.</p></blockquote></li>
+  </ul>
+  <p><img src="/img/diagram-${i}.png" alt="Diagram ${i}" width="600" height="400"> <span class="caption">Figure ${i}.</span></p>
+  <hr>
+</section>`;
+
+function page(sections) {
+  let nav = "";
+  for (let i = 0; i < sections; i++) nav += `<li><a href="#s${i}">Section ${i}</a></li>`;
+  let body = "";
+  for (let i = 0; i < sections; i++) body += section(i);
+  return `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Bench page</title>
+<style>body{font-family:sans-serif}.heading{color:#333}</style>
+<script>window.dataLayer=[];function gtag(){dataLayer.push(arguments)}</script></head>
+<body><header><nav><ul>${nav}</ul></nav></header><main><article><h1>Benchmark <em>page</em></h1>${body}</article></main>
+<footer><p>&copy; 2025 Example &middot; <a href="/privacy">Privacy</a></p></footer>
+<script type="application/json">${JSON.stringify({ props: { sections } })}</script></body></html>`;
+}
+
+const inputs = [];
+const files = process.argv.slice(2);
+if (files.length) {
+  for (const f of files) inputs.push([basename(f), readFileSync(f, "utf8")]);
+} else {
+  for (const n of [2, 40, 400]) {
+    const html = page(n);
+    inputs.push([`${(html.length / 1024).toFixed(0)} KB page`, html]);
+  }
+}
+
+const hasBun = typeof Bun !== "undefined" && Bun.markdown && typeof Bun.markdown.fromHTML === "function";
+
+for (const [name, html] of inputs) {
+  group(name, () => {
+    if (hasBun) {
+      bench("Bun.markdown.fromHTML", () => Bun.markdown.fromHTML(html));
+    }
+    bench("turndown + gfm", () => td.turndown(html));
+  });
+}
+
+await run();
diff --git a/docs/runtime/markdown.mdx b/docs/runtime/markdown.mdx
@@ -7,11 +7,12 @@ description: Parse and render Markdown with Bun's built-in Markdown API, support
   **Unstable API** — This API is under active development and may change in future versions of Bun.
 </Callout>
 
-Bun includes a fast, built-in Markdown parser written in Rust. It supports GitHub Flavored Markdown (GFM) extensions and provides three APIs:
+Bun includes a fast, built-in Markdown parser written in Rust. It supports GitHub Flavored Markdown (GFM) extensions and provides these APIs:
 
 - `Bun.markdown.html()` — render Markdown to an HTML string
 - `Bun.markdown.render()` — render Markdown with custom callbacks for each element
 - `Bun.markdown.react()` — render Markdown to React JSX elements
+- `Bun.markdown.fromHTML()` — convert HTML to Markdown
 
 ---
 
@@ -379,3 +380,107 @@ const el = Bun.markdown.react("## Hello World", undefined, {
   autolinks: true,
 });
 ```
+
+---
+
+## `Bun.markdown.fromHTML()`
+
+Convert an HTML string to Markdown. This is the inverse of `Bun.markdown.html()`: it takes a document or fragment of HTML and produces GitHub Flavored Markdown.
+
+```ts
+const md = Bun.markdown.fromHTML("<h1>Hello <em>world</em></h1><p>See <a href='https://bun.com'>bun.com</a>.</p>");
+// "# Hello _world_\n\nSee [bun.com](https://bun.com)."
+```
+
+Whole pages work the same way as fragments:
+
+```ts
+const res = await fetch("https://bun.com/docs/runtime/markdown");
+const md = Bun.markdown.fromHTML(await res.text());
+```
+
+Bun tokenizes the input with the same parser that powers [`HTMLRewriter`](/runtime/html-rewriter) and applies the HTML tree-construction rules that decide structure: omitted end tags (`<p>a<p>b`, `<li>`, `<td>`), mis-nested inline formatting, and table sections are recovered the way a browser recovers them. The conversion never throws on bad HTML. Only `<body>` content is converted. `<script>`, `<style>`, `<template>`, and `<noscript>` elements are dropped together with their contents, as if they were not in the document, and comments are ignored.
+
+GFM output is on by default. Tables become pipe tables, `<del>` becomes `~~strikethrough~~`, and checkboxes at the start of list items become task list markers:
+
+```ts
+const md = Bun.markdown.fromHTML(`
+  <table>
+    <thead><tr><th>Feature</th><th align="right">Status</th></tr></thead>
+    <tbody><tr><td>Tables</td><td><del>todo</del> done</td></tr></tbody>
+  </table>
+  <ul><li><input type="checkbox" checked> shipped</li></ul>
+`);
+```
+
+{/* prettier-ignore */}
+```md
+| Feature | Status |
+| --- | --: |
+| Tables | ~~todo~~ done |
+
+- [x] shipped
+```
+
+### Conversion rules
+
+The rules follow [turndown](https://github.com/mixmark-io/turndown), the most widely used JavaScript HTML-to-Markdown converter, with its GFM plugin:
+
+| HTML                                                    | Markdown                                                                                                                                                        |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<h1>`–`<h6>`                                           | `#` headings                                                                                                                                                    |
+| `<p>`, `<div>`, `<section>`, other block elements       | Paragraphs separated by a blank line                                                                                                                            |
+| `<br>`                                                  | Hard line break                                                                                                                                                 |
+| `<hr>`                                                  | `---`                                                                                                                                                           |
+| `<em>`, `<i>`                                           | `_text_`                                                                                                                                                        |
+| `<strong>`, `<b>`                                       | `**text**`                                                                                                                                                      |
+| `<del>`, `<s>`, `<strike>`                              | `~~text~~`                                                                                                                                                      |
+| `<code>`                                                | `` `text` ``                                                                                                                                                    |
+| `<pre>`                                                 | Fenced code block. A `language-*` or `lang-*` class on the `<pre>` or its `<code>` (or a `highlight-source-*` class on a wrapping `<div>`) sets the info string |
+| `<a href>`                                              | `[text](href "title")`                                                                                                                                          |
+| `<img src>`                                             | `![alt](src "title")`                                                                                                                                           |
+| `<ul>`, `<ol>`, `<li>`                                  | `-` and `1.` list items, nested by indentation. `<ol start>` is honored                                                                                         |
+| `<blockquote>`                                          | `>` quoted lines                                                                                                                                                |
+| `<table>`                                               | GFM pipe table. The first row becomes the header row. `align` and `text-align` set column alignment                                                             |
+| `<input type="checkbox">` at the start of an `<li>`     | `[x]` or `[ ]`                                                                                                                                                  |
+| Anything else (`<span>`, `<sup>`, custom elements, SVG) | Its text content                                                                                                                                                |
+
+Characters in text that Markdown would otherwise treat as syntax (`*`, `_`, `` ` ``, `[`, `\`, and at the start of a line `-`, `+`, `#`, `>`, `=` or `1.`) are backslash-escaped, so the output renders back to the same text.
+
+Pipe-table cells cannot hold block content, so paragraphs, lists, and line breaks inside a table cell are joined onto one line. A table that cannot form a grid, such as a single cell or a layout table that wraps other tables, is unwrapped into ordinary blocks instead.
+
+Whitespace is collapsed the way a browser renders it: runs of spaces and newlines become a single space, except inside `<pre>`.
+
+### Options
+
+Pass an options object as the second argument. Every option chooses between equivalent Markdown spellings or toggles a GFM extension:
+
+```ts
+Bun.markdown.fromHTML("<ul><li>one</li></ul><hr>", {
+  bulletListMarker: "*",
+  hr: "***",
+});
+// "* one\n\n***"
+```
+
+| Option             | Values                                                     | Default    | Description                                                                         |
+| ------------------ | ---------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------- |
+| `headingStyle`     | `"atx"`, `"setext"`                                        | `"atx"`    | `"setext"` underlines `<h1>` and `<h2>` with `===` and `---`                        |
+| `hr`               | `"---"`, `"***"`, `"___"`, `"- - -"`, `"* * *"`, `"_ _ _"` | `"---"`    | Thematic break for `<hr>`                                                           |
+| `bulletListMarker` | `"-"`, `"*"`, `"+"`                                        | `"-"`      | Marker for `<ul>` items                                                             |
+| `codeBlockStyle`   | `"fenced"`, `"indented"`                                   | `"fenced"` | `"indented"` writes four-space indented code blocks with no info string             |
+| `fence`            | `"```"`, `"~~~"`                                           | `"```"`    | Fence for code blocks. It grows automatically when the code contains the same run   |
+| `emDelimiter`      | `"_"`, `"*"`                                               | `"_"`      | Delimiter for `<em>`                                                                |
+| `strongDelimiter`  | `"**"`, `"__"`                                             | `"**"`     | Delimiter for `<strong>`                                                            |
+| `br`               | `"  "`, `"\\"`                                             | `"  "`     | How a `<br>` ends its line: two spaces or a backslash                               |
+| `tables`           | `boolean`                                                  | `true`     | Write GFM pipe tables. When `false`, table cells become consecutive blocks          |
+| `strikethrough`    | `boolean`                                                  | `true`     | Write `~~text~~` for `<del>`. When `false`, the text is kept without markup         |
+| `tasklists`        | `boolean`                                                  | `true`     | Write `[x]` / `[ ]` for list-item checkboxes. When `false`, the checkbox is dropped |
+
+An unrecognized option value throws a `TypeError`.
+
+### Input
+
+`fromHTML()` accepts a string or any `TypedArray`, `DataView`, or `ArrayBuffer` holding UTF-8 bytes. Invalid UTF-8 sequences in a buffer are replaced with U+FFFD, as a browser does.
+
+Conversion time and memory are linear in the size of the input, including for hostile markup. Like browsers, Bun stops nesting elements past a depth of 512 and keeps their text in the deepest open element, with block boundaries reduced to spaces.