From 7717813ee7abe2dc08377d9b5721068dfeaf1f5b Mon Sep 17 00:00:00 2001
From: leaysgur <6259812+leaysgur@users.noreply.github.com>
Date: Fri, 18 Sep 2026 08:28:32 +0000
Subject: [PATCH] feat(formatter_markdown): implement markdown formatter
 (#26434)

- [x] Add `oxc_formatter_markdown` crate
  - `publish = false` as always
- [x] Implement basic syntax formatting
- [x] Implement GFM, extended syntaxes
- [x] Support directive container `::: foo`
- [x] Fixed reported, upstream bugs
- [x] Publish `oxc_markdown_parser` and use it
- [x] Bump `Cargo.toml` version
- [x] ~~Embedded code fence w/ Oxfmt integration~~ => Later PR
---
 .gitattributes                                |   1 +
 .github/CODEOWNERS                            |   1 +
 .github/workflows/ci.yml                      |   6 +-
 Cargo.lock                                    |  26 +
 Cargo.toml                                    |   1 +
 crates/oxc_formatter_core/FORMATTER_POLICY.md |   1 +
 crates/oxc_formatter_markdown/AGENTS.md       |  96 +++
 crates/oxc_formatter_markdown/CLAUDE.md       |   1 +
 crates/oxc_formatter_markdown/Cargo.toml      |  39 +
 crates/oxc_formatter_markdown/DIVERGENCES.md  | 421 ++++++++++
 crates/oxc_formatter_markdown/build.rs        |  15 +
 .../examples/markdown_formatter.rs            |  74 ++
 crates/oxc_formatter_markdown/src/context.rs  | 143 ++++
 crates/oxc_formatter_markdown/src/format.rs   | 119 +++
 crates/oxc_formatter_markdown/src/lib.rs      |  26 +
 crates/oxc_formatter_markdown/src/options.rs  |  92 +++
 .../oxc_formatter_markdown/src/print/block.rs | 390 +++++++++
 .../src/print/blockquote.rs                   |  22 +
 .../oxc_formatter_markdown/src/print/cjk.rs   | 181 +++++
 .../oxc_formatter_markdown/src/print/code.rs  |  67 ++
 .../src/print/escape.rs                       | 113 +++
 .../src/print/inline.rs                       | 754 ++++++++++++++++++
 .../src/print/line_shape.rs                   | 201 +++++
 .../oxc_formatter_markdown/src/print/link.rs  | 277 +++++++
 .../oxc_formatter_markdown/src/print/list.rs  | 311 ++++++++
 .../oxc_formatter_markdown/src/print/mod.rs   | 177 ++++
 .../src/print/pairing.rs                      | 105 +++
 .../oxc_formatter_markdown/src/print/parts.rs | 194 +++++
 .../oxc_formatter_markdown/src/print/table.rs | 120 +++
 .../oxc_formatter_markdown/src/print/text.rs  | 361 +++++++++
 .../tests/conformance.rs                      | 103 +++
 .../tests/fixtures/fingerprint.rs             | 344 ++++++++
 .../tests/fixtures/markdown/basic.md          |  26 +
 .../tests/fixtures/markdown/basic.md.snap     |  93 +++
 .../fixtures/markdown/indented-code-tab.md    |   3 +
 .../markdown/indented-code-tab.md.snap        |  24 +
 .../markdown/link-url-special-chars.md        |  10 +
 .../markdown/link-url-special-chars.md.snap   |  47 ++
 .../markdown/list-multiline-inline.md         |  20 +
 .../markdown/list-multiline-inline.md.snap    |  75 ++
 .../tests/fixtures/markdown/oxfmt-ignore.md   |  13 +
 .../fixtures/markdown/oxfmt-ignore.md.snap    |  54 ++
 .../tests/fixtures/markdown/prose-wrap/cjk.md |  23 +
 .../fixtures/markdown/prose-wrap/cjk.md.snap  | 156 ++++
 .../prose-wrap/container-directive.md         |  21 +
 .../prose-wrap/container-directive.md.snap    | 172 ++++
 .../ignored-block-trailing-quote-line.md      |   8 +
 .../ignored-block-trailing-quote-line.md.snap |  81 ++
 .../markdown/prose-wrap/line-shapes.md        |  20 +
 .../markdown/prose-wrap/line-shapes.md.snap   | 175 ++++
 .../markdown/prose-wrap/liquid-flow.md        |  11 +
 .../markdown/prose-wrap/liquid-flow.md.snap   | 108 +++
 .../fixtures/markdown/prose-wrap/options.json |   1 +
 .../markdown/prose-wrap/stray-delimiters.md   |  24 +
 .../prose-wrap/stray-delimiters.md.snap       | 203 +++++
 .../prose-wrap/wiki-link-code-span.md         |   4 +
 .../prose-wrap/wiki-link-code-span.md.snap    |  59 ++
 .../markdown/prose-wrap/wrap-block-starts.md  |  32 +
 .../prose-wrap/wrap-block-starts.md.snap      | 256 ++++++
 .../tests/fixtures/markdown/single-tilde.md   |   3 +
 .../fixtures/markdown/single-tilde.md.snap    |  24 +
 .../tab-width-4/indented-code-block.md        |  17 +
 .../tab-width-4/indented-code-block.md.snap   |  66 ++
 .../markdown/tab-width-4/list-html-block.md   |  23 +
 .../tab-width-4/list-html-block.md.snap       |  84 ++
 .../tab-width-4/list-indented-code.md         |  14 +
 .../tab-width-4/list-indented-code.md.snap    |  57 ++
 .../markdown/tab-width-4/options.json         |   1 +
 .../fixtures/markdown/thematic-break-first.md |   5 +
 .../markdown/thematic-break-first.md.snap     |  30 +
 .../tests/fixtures/mod.rs                     |  83 ++
 .../tests/fixtures/options.rs                 |  42 +
 .../tests/invariants.rs                       | 303 +++++++
 crates/oxc_formatter_markdown/tests/mod.rs    |   1 +
 .../conformance__prettier-markdown.snap       |  26 +
 oxc_release.toml                              |   1 +
 76 files changed, 7278 insertions(+), 3 deletions(-)
 create mode 100644 crates/oxc_formatter_markdown/AGENTS.md
 create mode 100644 crates/oxc_formatter_markdown/CLAUDE.md
 create mode 100644 crates/oxc_formatter_markdown/Cargo.toml
 create mode 100644 crates/oxc_formatter_markdown/DIVERGENCES.md
 create mode 100644 crates/oxc_formatter_markdown/build.rs
 create mode 100644 crates/oxc_formatter_markdown/examples/markdown_formatter.rs
 create mode 100644 crates/oxc_formatter_markdown/src/context.rs
 create mode 100644 crates/oxc_formatter_markdown/src/format.rs
 create mode 100644 crates/oxc_formatter_markdown/src/lib.rs
 create mode 100644 crates/oxc_formatter_markdown/src/options.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/block.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/blockquote.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/cjk.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/code.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/escape.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/inline.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/line_shape.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/link.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/list.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/mod.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/pairing.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/parts.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/table.rs
 create mode 100644 crates/oxc_formatter_markdown/src/print/text.rs
 create mode 100644 crates/oxc_formatter_markdown/tests/conformance.rs
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/fingerprint.rs
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/basic.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/basic.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/indented-code-tab.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/indented-code-tab.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/link-url-special-chars.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/link-url-special-chars.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/list-multiline-inline.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/list-multiline-inline.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/oxfmt-ignore.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/oxfmt-ignore.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/cjk.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/cjk.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/container-directive.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/container-directive.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/ignored-block-trailing-quote-line.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/ignored-block-trailing-quote-line.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/line-shapes.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/line-shapes.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/liquid-flow.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/liquid-flow.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/options.json
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/stray-delimiters.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/stray-delimiters.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wiki-link-code-span.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wiki-link-code-span.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wrap-block-starts.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wrap-block-starts.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/single-tilde.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/single-tilde.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/indented-code-block.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/indented-code-block.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-html-block.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-html-block.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-indented-code.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-indented-code.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/options.json
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/thematic-break-first.md
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/markdown/thematic-break-first.md.snap
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/mod.rs
 create mode 100644 crates/oxc_formatter_markdown/tests/fixtures/options.rs
 create mode 100644 crates/oxc_formatter_markdown/tests/invariants.rs
 create mode 100644 crates/oxc_formatter_markdown/tests/mod.rs
 create mode 100644 crates/oxc_formatter_markdown/tests/snapshots/conformance__prettier-markdown.snap

diff --git a/.gitattributes b/.gitattributes
index 520bcef6e6..ea926c4b67 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -7,6 +7,7 @@ crates/oxc_formatter_graphql/tests/fixtures/** text=auto eol=lf
 crates/oxc_formatter_graphql/tests/fixtures/graphql/crlf/** text=auto eol=crlf
 crates/oxc_formatter_yaml/tests/fixtures/** text=auto eol=lf
 crates/oxc_formatter_yaml/tests/fixtures/yaml/crlf/** text=auto eol=crlf
+crates/oxc_formatter_markdown/tests/fixtures/** text=auto eol=lf
 apps/oxfmt/test/**/fixtures/** text=auto eol=lf
 apps/oxlint/test/fixtures/** text=auto eol=lf
 
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 0ab1842145..7f4db6481a 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -33,6 +33,7 @@ pnpm-lock.yaml
 /crates/oxc_formatter_graphql @leaysgur
 /crates/oxc_formatter_css @leaysgur
 /crates/oxc_formatter_yaml @leaysgur
+/crates/oxc_formatter_markdown @leaysgur
 /crates/oxc_formatter_tests @leaysgur
 /crates/oxc_jsdoc @leaysgur
 /crates/oxc_regular_expression @leaysgur
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 36758bbd1f..e39d15412a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -300,13 +300,13 @@ jobs:
       - uses: ./.github/actions/check-changes
         id: filter
         with:
-          paths: apps/oxfmt/,apps/shared/,npm/oxfmt/,crates/oxc_formatter/,crates/oxc_formatter_core/,crates/oxc_formatter_css/,crates/oxc_formatter_graphql/,crates/oxc_formatter_json/,crates/oxc_formatter_yaml/,crates/oxc_config/,pnpm-lock.yaml,package.json
+          paths: apps/oxfmt/,apps/shared/,npm/oxfmt/,crates/oxc_formatter/,crates/oxc_formatter_core/,crates/oxc_formatter_css/,crates/oxc_formatter_graphql/,crates/oxc_formatter_json/,crates/oxc_formatter_yaml/,crates/oxc_formatter_markdown/,crates/oxc_config/,pnpm-lock.yaml,package.json
           token: ${{ secrets.GITHUB_TOKEN }}
           pr-number: ${{ github.event.pull_request.number }}
       - uses: ./.github/actions/check-changes
         id: filter-conformance
         with:
-          paths: apps/oxfmt/,npm/oxfmt/,crates/oxc_formatter/,crates/oxc_formatter_core/,crates/oxc_formatter_css/,crates/oxc_formatter_graphql/,crates/oxc_formatter_json/,crates/oxc_formatter_yaml/,pnpm-lock.yaml,package.json
+          paths: apps/oxfmt/,npm/oxfmt/,crates/oxc_formatter/,crates/oxc_formatter_core/,crates/oxc_formatter_css/,crates/oxc_formatter_graphql/,crates/oxc_formatter_json/,crates/oxc_formatter_yaml/,crates/oxc_formatter_markdown/,pnpm-lock.yaml,package.json
           token: ${{ secrets.GITHUB_TOKEN }}
           pr-number: ${{ github.event.pull_request.number }}
       - uses: oxc-project/setup-node@f46a72f95efdc55273fcd042d61c84e723b2892c # v1.4.1
@@ -454,7 +454,7 @@ jobs:
       - uses: ./.github/actions/check-changes
         id: filter
         with:
-          paths: apps/oxfmt/,apps/shared/,npm/oxfmt/,crates/oxc_formatter/,crates/oxc_formatter_core/,crates/oxc_formatter_css/,crates/oxc_formatter_graphql/,crates/oxc_formatter_json/,crates/oxc_formatter_yaml/,crates/oxc_config/,pnpm-lock.yaml,package.json
+          paths: apps/oxfmt/,apps/shared/,npm/oxfmt/,crates/oxc_formatter/,crates/oxc_formatter_core/,crates/oxc_formatter_css/,crates/oxc_formatter_graphql/,crates/oxc_formatter_json/,crates/oxc_formatter_yaml/,crates/oxc_formatter_markdown/,crates/oxc_config/,pnpm-lock.yaml,package.json
           token: ${{ secrets.GITHUB_TOKEN }}
           pr-number: ${{ github.event.pull_request.number }}
       - uses: samypr100/setup-dev-drive@562171fe8df7401fdf582d766cd3b6ab80d5b1a0 # v4.1.0
diff --git a/Cargo.lock b/Cargo.lock
index 7b17e77b50..6a4b680ee7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1705,6 +1705,15 @@ dependencies = [
  "thiserror",
 ]
 
+[[package]]
+name = "oxc-markdown-parser"
+version = "0.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "198e25a5dfc6aabe79614588816ec57612622d25e1eff291aae0542f7a0e3c18"
+dependencies = [
+ "oxc_allocator",
+]
+
 [[package]]
 name = "oxc-schemars"
 version = "0.9.1"
@@ -2129,6 +2138,23 @@ dependencies = [
  "pico-args",
 ]
 
+[[package]]
+name = "oxc_formatter_markdown"
+version = "0.68.0"
+dependencies = [
+ "cow-utils",
+ "insta",
+ "oxc-markdown-parser",
+ "oxc_allocator",
+ "oxc_diagnostics",
+ "oxc_formatter_core",
+ "oxc_formatter_tests",
+ "oxc_span",
+ "oxc_tasks_common",
+ "pico-args",
+ "serde_json",
+]
+
 [[package]]
 name = "oxc_formatter_tests"
 version = "0.62.0"
diff --git a/Cargo.toml b/Cargo.toml
index e7d7fde00a..dc86cc75f2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -241,6 +241,7 @@ num-bigint = "0.5.0" # Big integers
 num-traits = "0.2.19" # Numeric traits
 oxc-css-parser = "0.0.15" # CSS/SCSS/Less parser (raffia 0.12.3 fork: adds `template_placeholder` typed placeholders for css-in-js + valid-syntax coverage fixes (see crates/oxc_formatter_css/AGENTS.md))
 oxc-graphql-parser = "0.0.9" # GraphQL parser (direct AST; apollo-parser 0.8.6 fork aligned with graphql-js 17 syntax)
+oxc-markdown-parser = "0.0.0" # CommonMark + GFM parser (span-faithful, style-preserving typed AST)
 oxc-toml = "0.14.5" # TOML formatter
 oxc-yaml-parser = "0.0.6" # YAML 1.2 parser (comment-preserving typed AST, node naming from `yaml-unist-parser`)
 papaya = "0.2.4" # Concurrent hash map
diff --git a/crates/oxc_formatter_core/FORMATTER_POLICY.md b/crates/oxc_formatter_core/FORMATTER_POLICY.md
index 250b2372d0..4461cd62f7 100644
--- a/crates/oxc_formatter_core/FORMATTER_POLICY.md
+++ b/crates/oxc_formatter_core/FORMATTER_POLICY.md
@@ -7,6 +7,7 @@ Shared policy for every formatter crate in the oxc ecosystem:
 - `oxc_formatter_css`
 - `oxc_formatter_graphql`
 - `oxc_formatter_yaml`
+- `oxc_formatter_markdown`
 
 using `oxc_formatter_core`, integrated by `apps/oxfmt`.
 
diff --git a/crates/oxc_formatter_markdown/AGENTS.md b/crates/oxc_formatter_markdown/AGENTS.md
new file mode 100644
index 0000000000..0e935c091e
--- /dev/null
+++ b/crates/oxc_formatter_markdown/AGENTS.md
@@ -0,0 +1,96 @@
+# Coding agent guides for `crates/oxc_formatter_markdown`
+
+Follow @../oxc_formatter_core/FORMATTER_POLICY.md , this file holds only the Markdown-specific rules.
+Known divergences live in DIVERGENCES.md.
+
+## Overview
+
+Prettier compatible Markdown formatter on `oxc_formatter_core`.
+Entry points and their contracts are documented in `src/format.rs`.
+
+Parses with [`oxc-markdown-parser`](https://github.com/oxc-project/oxc-markdown-parser).
+Parse behavior targets micromark (what Prettier parses with); its AGENTS.md / DIVERGENCES.md are the reference.
+Style facts (markers, fence kind, setext, break kind, list padding, ...) are AST fields and `ParserReturn::blanks` lists the blank lines,
+so the printer never re-derives layout from the source text.
+Formatter policy (sentence splitting, CJK, aligned lists, escaping) stays here.
+
+### Escaping
+
+Text is printed as written. Escapes are added in three places only:
+
+- `*` / `_` runs inside emphasis
+- a lone `===` / `---` word starting a line
+- link destinations / titles / labels
+
+Emphasis marker normalization is verified before it is committed:
+`print/pairing.rs` runs the parser's delimiter resolver on the printed text and falls back to the markers as written when the nodes would differ.
+Plain text outside emphasis is never escaped and entities are never decoded;
+that is what keeps `snake_case`, `:emoji:`, `{#id}` attributes and `<Comp @click="a * b">` intact for every dialect.
+
+### Envelope
+
+Source is normalized to `\n` before parsing (verbatim slices go straight into the IR), the configured line ending is re-emitted at print time,
+a leading BOM is preserved.
+
+Front matter (`---` / `+++`) is not handled (`oxc_formatter_core::spec::parse_front_matter` + `envelope::write_front_matter`, as CSS does).
+
+## Dialects
+
+Markdown grammars are open-ended (VitePress, Docusaurus, Pandoc, kramdown, Obsidian, ...), and the parser learns none of them:
+a construct exists only when micromark / a Prettier extension parses it or GitHub renders it.
+The formatter keeps the rest intact without grammar: no escaping of plain text (see "Escaping" above) and line shapes.
+
+Line shapes (`line_shape::line_shape`): a paragraph line starting with `:::`, `<<<`, a component tag (`<Badge`, `<my-element`),
+or `[!` as the first line of a blockquote keeps both its line boundaries and is never re-wrapped, under every `proseWrap`.
+The list is fixed and shape-based, not per dialect; `preserve` (the default) keeps every line anyway,
+so only `always` / `never` are affected. Add a shape only with a fixture in `tests/fixtures/markdown/prose-wrap/line-shapes.md`.
+
+When a dialect construct breaks: never add its grammar to the parser; add a shape (with the fixture), or record it below as a limit.
+
+Known limits (not handled, by decision):
+
+- kramdown IAL lines (`{: .class}` gets a blank line before it)
+- MDX ESM in `.md` (Docusaurus; `import` lines re-wrap)
+- 4-space nested lists re-indented to 2 (`tabWidth: 4` keeps them)
+- Pandoc simple / grid tables, Python-Markdown admonitions without a blank line before them
+
+## Verification
+
+```sh
+cargo run -p oxc_formatter_markdown --example markdown_formatter [filename]
+DUMP_IR=1 cargo run -p oxc_formatter_markdown --example markdown_formatter [filename]
+
+# The oracle. Without `--no-config --no-editorconfig` the repo's `.editorconfig` changes the output
+node apps/oxfmt/node_modules/prettier/bin/prettier.cjs --parser markdown --no-config --no-editorconfig [filename]
+# Prettier's doc, when the output alone does not explain a layout
+node -e 'const p=require("./apps/oxfmt/node_modules/prettier");p.__debug.printToDoc(require("fs").readFileSync(process.argv[1],"utf8"),{parser:"markdown"}).then(d=>p.__debug.formatDoc(d)).then(console.log)' [filename]
+```
+
+### Prettier conformance
+
+At the current version (v3.9.6), these divergences have been confirmed and are intentional (see DIVERGENCES.md):
+
+Conformance failures classified as divergences (16, all of them):
+
+- `thematicBreak/simple.md` and `commonmark-test-suite/snippet: example-11.md`, `example-50.md` to `example-54.md` (`#leading-thematic-break`)
+- `commonmark-test-suite/snippet: example-2.md` (`#indented-code-tab`)
+- `link/encodedLink.md` (`#url-escaping`)
+- `gfm-test-suite/snippet: example-491.md` (`#single-tilde-strikethrough`)
+- `liquid/*.md` (`#liquid-flow-tags`)
+- `blockquote/notext-end.md` (`#line-shapes`)
+- `paragraph/cjk.md` (`#container-directive`)
+- `commonmark-test-suite/snippet: example-412.md` (`#stray-delimiters`)
+
+### Fixture fingerprint
+
+`tests/fixtures/fingerprint.rs` serializes the AST's meaning (structure, decoded text, destinations, labels) and ignores what formatting may change
+(spans, markers, fence style, text splitting, whitespace runs, tightness, whitespace next to Chinese / Japanese characters, trailing whitespace of verbatim lines, info string whitespace).
+The harness asserts it is identical for input and output: every fixture is a `parse(format(x)) ≅ parse(x)` check, which idempotency alone cannot give (a corrupted output is often a fixpoint).
+Extend the ignore set only with a reason written next to it.
+
+### Fuzzed invariants
+
+`tests/invariants.rs` formats a deterministic token-soup corpus (the parser repo's differential generator) under every `proseWrap` and checks the fingerprint and idempotency.
+The default corpus must fail exactly on `KNOWN_FAILURES` (the documents and their classes are listed there);
+remove an entry when its class is fixed, any other failure is a regression.
+`MD_FUZZ_SEED` / `MD_FUZZ_COUNT` run other corpora, `MD_FUZZ_FILE` prints one document's fingerprints.
diff --git a/crates/oxc_formatter_markdown/CLAUDE.md b/crates/oxc_formatter_markdown/CLAUDE.md
new file mode 100644
index 0000000000..43c994c2d3
--- /dev/null
+++ b/crates/oxc_formatter_markdown/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/crates/oxc_formatter_markdown/Cargo.toml b/crates/oxc_formatter_markdown/Cargo.toml
new file mode 100644
index 0000000000..d46d96e878
--- /dev/null
+++ b/crates/oxc_formatter_markdown/Cargo.toml
@@ -0,0 +1,39 @@
+[package]
+name = "oxc_formatter_markdown"
+version = "0.68.0"
+authors.workspace = true
+categories.workspace = true
+edition.workspace = true
+homepage.workspace = true
+include = ["/src"]
+keywords.workspace = true
+license.workspace = true
+publish = false
+repository.workspace = true
+rust-version.workspace = true
+description.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+cow-utils = { workspace = true }
+oxc-markdown-parser = { workspace = true }
+oxc_allocator = { workspace = true }
+oxc_diagnostics = { workspace = true }
+oxc_formatter_core = { workspace = true }
+oxc_span = { workspace = true }
+
+[dev-dependencies]
+insta = { workspace = true }
+oxc_formatter_tests = { workspace = true, features = ["conformance"] }
+oxc_tasks_common = { workspace = true }
+pico-args = { workspace = true }
+serde_json = { workspace = true }
+
+[build-dependencies]
+oxc_formatter_tests = { workspace = true }
+
+[lib]
+doctest = false
+test = false
diff --git a/crates/oxc_formatter_markdown/DIVERGENCES.md b/crates/oxc_formatter_markdown/DIVERGENCES.md
new file mode 100644
index 0000000000..40f679ffc2
--- /dev/null
+++ b/crates/oxc_formatter_markdown/DIVERGENCES.md
@@ -0,0 +1,421 @@
+# Known divergences
+
+Admission reasons and rules: see `crates/oxc_formatter_core/FORMATTER_POLICY.md` "Known divergences".
+
+## leading-thematic-break
+
+- Why: semantics (prettier/prettier#19839)
+- Pin: `tests/fixtures/markdown/thematic-break-first.md`
+
+```markdown
+<!-- input -->
+---
+
+text
+
+---
+
+<!-- ours -->
+***
+
+text
+
+---
+
+<!-- prettier -->
+---
+
+text
+
+---
+```
+
+A document whose first block is a thematic break gets `***`, never `---`:
+Prettier's own next run would read `---` ... `---` as front matter and swallow `text` into it.
+Prettier `main` prints `***` since #19839; the pin (3.9.6) still prints `---`.
+
+## url-escaping
+
+- Why: semantics (prettier/prettier#19482, prettier/prettier#19849, prettier/prettier#19891)
+- Pin: `tests/fixtures/markdown/link-url-special-chars.md`
+
+```markdown
+<!-- input -->
+[a](https://x/()foo->bar)
+
+<!-- ours -->
+[a](<https://x/()foo-\>bar>)
+
+<!-- prettier -->
+[a](<https://x/()foo-%3Ebar>)
+```
+
+Destinations follow Prettier `main`: `<`, `>` inside the angle brackets are backslash-escaped (the pin percent-encodes them, which changes the URL),
+a `\` that would start an escape is doubled, and `&` that would start a character reference becomes `\&`
+(the pin drops the escape and the reference is decoded on the next parse).
+Titles get the same `\&` treatment.
+
+## indented-code-tab
+
+- Why: uniform-rule (same construct, same output: space-indented code block)
+- Pin: `tests/fixtures/markdown/indented-code-tab.md`
+
+````markdown
+<!-- input: two spaces, a tab -->
+  	foo
+
+<!-- ours -->
+    foo
+
+<!-- prettier -->
+```
+foo
+```
+````
+
+An indented code block is printed indented, however its 4 columns were written.
+Prettier recognizes indented code from the raw text with a regex (four spaces or a tab),
+so an indent written as spaces plus a tab becomes a fenced block.
+
+## ignored-block-trailing-quote-line
+
+- Why: uniform-rule (same construct, same output: the `proseWrap: preserve` layout)
+- Pin: `tests/fixtures/markdown/prose-wrap/ignored-block-trailing-quote-line.md`
+
+```markdown
+<!-- input -->
+> <!-- prettier-ignore -->
+> - a   long   item
+>
+
+> next
+
+<!-- ours -->
+> <!-- prettier-ignore -->
+> - a   long   item
+
+> next
+
+<!-- prettier, proseWrap: always -->
+> <!-- prettier-ignore -->
+> - a   long   item
+>
+
+> next
+```
+
+A blockquote's trailing blank `>` line is dropped, whatever `proseWrap` is.
+Prettier drops it under `preserve` and `never` but prints a bare `>` under `always` when the block before it is `prettier-ignore`d.
+
+## list-indented-code-alignment
+
+- Why: semantics (prettier/prettier#19644, prettier/prettier#19647, prettier/prettier#19990)
+- Pin: `tests/fixtures/markdown/tab-width-4/list-indented-code.md`, `tests/fixtures/markdown/tab-width-4/indented-code-block.md`
+
+```markdown
+<!-- input, tabWidth 4 -->
+- foo
+
+      code
+
+<!-- ours -->
+- foo
+
+      code
+
+<!-- prettier -->
+- foo
+
+        code
+```
+
+An indented code block inside a list item is printed at the item's content column + 4, nothing more:
+the code's content is exactly what follows that column, so any extra alignment becomes part of it on the next parse.
+The pin aligns it by the task checkbox (continuation lines drift by 4 per run, #19644);
+#19647 aligned it by the tab width instead, which shifted the content whenever `tabWidth` exceeded the marker width.
+Prettier `main` prints it as we do since #19990 (`indented-code-block.md` is its fixture); the pin (3.9.6) still differs.
+
+The same rule keeps the marker of an ordered list unpadded when an item starts with indented code
+(the content column is the marker plus one space, so any padding lands inside the code).
+Prettier pads it when the code starts at a tab stop in the source, which `>2.     foo` does only because of the `>`:
+
+```markdown
+<!-- input -->
+>2.     foo
+
+<!-- ours -->
+> 2.     foo
+
+<!-- prettier (the code becomes " foo") -->
+> 2.      foo
+```
+
+An HTML block after a task item's paragraph keeps the item's content column too
+(Prettier drops the alignment when the html starts at another column than the paragraph, which moves it out of the item):
+
+```markdown
+<!-- input -->
+- [ ] a
+
+  <textarea>
+
+<!-- ours -->
+- [ ] a
+
+  <textarea>
+
+<!-- prettier (the html leaves the list) -->
+- [ ] a
+
+<textarea>
+```
+
+An HTML block closed by its container's end (`><script>a` then a list) carries that line ending as content;
+Prettier prints it, and inside a blockquote the block gains a `>` line on every pass. It is not printed.
+
+## list-marker-after-ignored-list
+
+- Why: semantics
+- Pin: `tests/fixtures/markdown/oxfmt-ignore.md`
+
+```markdown
+<!-- input -->
+<!-- prettier-ignore -->
+*   kept   as   written
+
+- formatted
+
+<!-- ours -->
+<!-- prettier-ignore -->
+*   kept   as   written
+
+- formatted
+
+<!-- prettier -->
+<!-- prettier-ignore -->
+*   kept   as   written
+
+* formatted
+```
+
+Adjacent lists alternate markers so they stay two lists. A list kept verbatim by `prettier-ignore` shows its own marker, so the list after it takes the other one;
+Prettier alternates from the marker it would have printed (`-`), prints `*` next to the verbatim `*` list, and the two merge into one list on the next parse.
+
+## single-tilde-strikethrough
+
+- Why: semantics (prettier/prettier#19739)
+- Pin: `tests/fixtures/markdown/single-tilde.md`
+
+```markdown
+<!-- input -->
+H~2~O
+
+<!-- ours -->
+H~2~O
+
+<!-- prettier -->
+H~~2~~O
+```
+
+A single-tilde span is not strikethrough (GitHub strikes `~~x~~` only) and is kept as written.
+The pin (3.9.6) parses it as strikethrough and rewrites it to `~~`, turning subscripts into strikes;
+Prettier `main` preserves it since #19739.
+
+## liquid-flow-tags
+
+- Why: semantics (prettier/prettier#19724, prettier/prettier#19838)
+- Pin: `tests/fixtures/markdown/prose-wrap/liquid-flow.md`
+
+```markdown
+<!-- input -->
+{% css a %}
+{% js b %}
+
+{{ foo
+
+bar   baz }}
+
+<!-- ours -->
+{% css a %}
+{% js b %}
+
+{{ foo
+
+bar   baz }}
+
+<!-- prettier, proseWrap always -->
+{% css a %} {% js b %}
+
+{{ foo
+
+bar baz }}
+```
+
+A liquid tag standing on its own line is a flow node: it is kept verbatim, blank lines inside included,
+and two tags on adjacent lines stay on their lines.
+The pin (3.9.6) reads them as inline tags in a paragraph, so `always` joins them and a tag spanning a blank line falls apart into paragraphs whose whitespace collapses;
+Prettier `main` parses them as flow nodes since #19838.
+
+## container-directive
+
+- Why: semantics
+- Pin: `tests/fixtures/markdown/prose-wrap/container-directive.md`
+
+```markdown
+<!-- input -->
+:::warning
+Some **text** that is
+long.
+:::
+
+<!-- ours, proseWrap always -->
+:::warning
+Some **text** that is long.
+:::
+
+<!-- prettier, proseWrap always -->
+:::warning Some **text** that is long. :::
+```
+
+A `:::` container directive (VitePress, Docusaurus, remark-directive, Pandoc) is a block:
+its fence lines are printed as written and only its children are formatted.
+The parser opens one on any name-like fence line (`:::name[label]{attrs}`, `::: tip Title`, `::: {.class}`; parser DIVERGENCES.md).
+
+Prettier has no directive construct (#19662 would add micromark's grammar only), so under `always` / `never` the fences are words of the paragraph and wrapping merges them into the text, which breaks the container for every dialect that reads it.
+
+## line-shapes
+
+- Why: semantics
+- Pin: `tests/fixtures/markdown/prose-wrap/line-shapes.md`
+
+```markdown
+<!-- input -->
+> [!NOTE]
+> `DOOM`
+
+<!-- ours, proseWrap always -->
+> [!NOTE]
+> `DOOM`
+
+<!-- prettier, proseWrap always -->
+> [!NOTE] `DOOM`
+```
+
+A paragraph line starting with `<<<` (VitePress snippet import), a component tag (`<Badge />`, `<my-element>`),
+a stray `:::`, or `[!` as the first line of a blockquote (GitHub / Obsidian alert marker) keeps its line boundaries and is never re-wrapped (AGENTS.md "Dialects").
+Prettier joins and wraps them like any word: the alert above loses its marker line (GitHub needs `[!NOTE]` alone on it),
+a wrapped `<<<` line loses its `[title]`, and a component tag wrapped to column 0 opens an HTML block in MDX / VitePress.
+`blockquote/notext-end.md` is the conformance failure.
+
+## wrapped-block-starts
+
+- Why: semantics (prettier/prettier#13634, prettier/prettier#19112, prettier/prettier#19847)
+- Pin: `tests/fixtures/markdown/prose-wrap/wrap-block-starts.md`
+
+```markdown
+<!-- input, proseWrap always -->
+Some words that push the tag to the edge of the line so the html block <div>x</div> lands first.
+
+<!-- ours -->
+Some words that push the tag to the edge of the line so the html block <div>x</div>
+lands first.
+
+<!-- prettier -->
+Some words that push the tag to the edge of the line so the html block
+<div>x</div> lands first.
+```
+
+A line break is never inserted before a word that would open a block at a line start.
+The parser's `lexical::line_start` decides, asked about the line the wrap would produce
+(`- x` interrupts a paragraph, an empty `-` does not; `*** x` is text, `***` alone is a break).
+Prettier tests a regex of list markers, `#`s and `>` only, so a wrapped `<div>`, `<!--`, `***`, `---`, fence,
+`|` row or `[^x]:` opens a block on the next parse.
+
+A kept line break (`proseWrap: preserve`) is dropped by the same rule when its next line only stays text
+by its indentation, which a paragraph does not keep: `| x | y |` over an 8-space `|---|---|` prints as one line,
+Prettier's `|---|---|` at column 0 is a table on the next parse (prettier/prettier#19847).
+Prettier drops the break before `- item`, `# heading` and `> quote` itself.
+
+## stray-delimiters
+
+- Why: semantics (prettier/prettier#6035, prettier/prettier#17303, prettier/prettier#17353)
+- Pin: `tests/fixtures/markdown/prose-wrap/stray-delimiters.md`
+
+```markdown
+<!-- input -->
+A stray ` backtick and then ``code``.
+
+<!-- ours -->
+A stray ` backtick and then ``code``.
+
+<!-- prettier -->
+A stray ` backtick and then `code`.
+```
+
+A code span keeps a longer fence when a literal backtick run of the shorter length precedes it;
+Prettier picks the shortest fence from the content alone, so its output pairs with the stray run and moves the span.
+
+Emphasis markers are normalized (`__` to `**`, `_` / `*` by their neighbors) only when the printed text
+still forms the same nodes: the parser's own resolver (`oxc_markdown_parser::attention::pairs`) is run on
+the runs of the text about to be printed, and on a mismatch the paragraph is printed with its markers
+as written (`**a ***b*** c**` stays: `**a _**b**_ c**` reads differently, prettier/prettier#20048).
+Prettier always normalizes.
+
+A `*` / `_` run inside emphasis that could pair is escaped character by character
+(`\*\*\*`; Prettier's single backslash leaves `**`, which still pairs: `example-412.md`).
+Found by `tests/invariants.rs`, the fuzzed `parse(format(x)) ≅ parse(x)` check.
+
+## verbatim-inline-continuation
+
+- Why: semantics (prettier/prettier#19116)
+- Pin: `tests/fixtures/markdown/list-multiline-inline.md`
+
+```markdown
+<!-- input -->
+- [ ] a `x
+      y` b
+
+- [ ] c <!-- one
+      two -->
+
+<!-- ours -->
+- [ ] a `x
+      y` b
+
+- [ ] c <!-- one
+      two -->
+
+<!-- prettier -->
+- [ ] a `x
+    y` b
+
+- [ ] c <!-- one
+          two -->
+```
+
+A continuation line of a verbatim inline node (code span, inline HTML, math span, image alt, link title)
+resumes at the container's content column, the only indentation the parser strips;
+whatever whitespace follows is the node's content and is printed as is.
+Prettier prints code span lines from column 0 and the others from its own alignment (a task item's checkbox counts there, not for the parser),
+so the content of `` `x y` `` loses two spaces per pass and an HTML comment gains four.
+
+## wiki-link-code-span
+
+- Why: semantics
+- Pin: `tests/fixtures/markdown/prose-wrap/wiki-link-code-span.md`
+
+```markdown
+<!-- input, proseWrap always -->
+See [[the `first
+second` note]] for details.
+
+<!-- ours -->
+See [[the `first
+second` note]] for details.
+
+<!-- prettier -->
+See [[the `first second` note]] for details.
+```
+
+In a paragraph printed as written for wiki link risk (Prettier's `riskyParagraphPositions`, `[[` ... `]]`),
+a code span keeps its line break too; Prettier joins it, and the one-line `[[...]]` is a wiki link on the next parse.
diff --git a/crates/oxc_formatter_markdown/build.rs b/crates/oxc_formatter_markdown/build.rs
new file mode 100644
index 0000000000..74e60f30dd
--- /dev/null
+++ b/crates/oxc_formatter_markdown/build.rs
@@ -0,0 +1,15 @@
+use std::{
+    env,
+    path::{Path, PathBuf},
+};
+
+use oxc_formatter_tests::{GenerateConfig, generate_tests};
+
+fn main() {
+    let out_dir = env::var("OUT_DIR").unwrap();
+    let dest_path = PathBuf::from(out_dir).join("generated_tests.rs");
+
+    let config = GenerateConfig { extensions: &["md"] };
+
+    generate_tests(&dest_path, Path::new("tests/fixtures"), &config).unwrap();
+}
diff --git a/crates/oxc_formatter_markdown/examples/markdown_formatter.rs b/crates/oxc_formatter_markdown/examples/markdown_formatter.rs
new file mode 100644
index 0000000000..7e3ecbc0a0
--- /dev/null
+++ b/crates/oxc_formatter_markdown/examples/markdown_formatter.rs
@@ -0,0 +1,74 @@
+#![expect(clippy::print_stdout)]
+//! # Markdown Formatter Example
+//!
+//! Handy for ad-hoc Prettier-compatibility checks:
+//! feed the same input to both `prettier` and this example, then diff the outputs.
+//!
+//! ## Usage
+//!
+//! Create a `test.md` file and run:
+//! ```bash
+//! cargo run -p oxc_formatter_markdown --example markdown_formatter [filename]
+//! cargo run -p oxc_formatter_markdown --example markdown_formatter -- --print-width 100 [filename]
+//! cargo run -p oxc_formatter_markdown --example markdown_formatter -- --prose-wrap always [filename]
+//! cargo run -p oxc_formatter_markdown --example markdown_formatter -- --diff [filename]
+//! ```
+
+use std::fs;
+
+use pico_args::Arguments;
+
+use oxc_allocator::Allocator;
+use oxc_formatter_core::LineWidth;
+use oxc_formatter_markdown::{MarkdownFormatOptions, ProseWrap};
+use oxc_tasks_common::print_diff_in_terminal;
+
+fn main() -> Result<(), String> {
+    let mut args = Arguments::from_env();
+    // Show diff between original and formatted code
+    let show_diff = args.contains("--diff");
+    let print_width = args.opt_value_from_str::<&'static str, u16>("--print-width").unwrap_or(None);
+    let prose_wrap =
+        args.opt_value_from_str::<&'static str, String>("--prose-wrap").unwrap_or(None);
+    let name = args.free_from_str().unwrap_or_else(|_| "test.md".to_string());
+
+    let source_text = fs::read_to_string(&name).map_err(|_| format!("Missing '{name}'"))?;
+
+    let line_width = match print_width {
+        Some(width) => LineWidth::try_from(width).unwrap(),
+        None => LineWidth::try_from(80).unwrap(),
+    };
+    let prose_wrap = match prose_wrap.as_deref() {
+        Some("always") => ProseWrap::Always,
+        Some("never") => ProseWrap::Never,
+        _ => ProseWrap::Preserve,
+    };
+    let options = MarkdownFormatOptions { line_width, prose_wrap, ..Default::default() };
+
+    let allocator = Allocator::new();
+    let formatted = match oxc_formatter_markdown::format(&allocator, &source_text, options) {
+        Ok(formatted) => formatted,
+        Err(error) => {
+            println!("{}", error.render());
+            return Err("Parsed with Errors.".to_string());
+        }
+    };
+
+    if std::env::var("DUMP_IR").is_ok() {
+        println!("{:#?}", formatted.document());
+    }
+
+    let formatted_code = formatted.print().unwrap().into_code();
+
+    if show_diff {
+        if source_text == formatted_code {
+            print!("{formatted_code}");
+        } else {
+            print_diff_in_terminal(&source_text, &formatted_code);
+        }
+    } else {
+        print!("{formatted_code}");
+    }
+
+    Ok(())
+}
diff --git a/crates/oxc_formatter_markdown/src/context.rs b/crates/oxc_formatter_markdown/src/context.rs
new file mode 100644
index 0000000000..c5058870f9
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/context.rs
@@ -0,0 +1,143 @@
+use std::cell::{Cell, RefCell};
+
+use oxc_formatter_core::{FormatContext, SourceText};
+use oxc_markdown_parser::Span;
+
+use crate::options::MarkdownFormatOptions;
+
+/// Formatting context for Markdown.
+pub struct MarkdownFormatContext<'a> {
+    options: MarkdownFormatOptions,
+    source_text: SourceText<'a>,
+    /// Every logical blank line, in source order (`ParserReturn::blanks`).
+    /// Blank runs between siblings carry meaning (loose lists, HTML verbatim boundaries),
+    /// so the printer consults this table instead of rescanning the source.
+    blanks: &'a [Span],
+    /// Enclosing lists, outermost first.
+    /// Prettier reads these off `path.ancestors`; this printer has no path, so containers push as they descend.
+    lists: RefCell<Vec<ListFrame>>,
+    /// Enclosing nodes whose content never wraps (ATX heading, link text).
+    no_wrap_depth: Cell<u32>,
+    /// Enclosing `Emphasis` nodes (marker choice for nested emphasis).
+    emphasis_depth: Cell<u32>,
+    /// Enclosing `Emphasis` or `Strong` nodes (delimiter-run escaping applies inside).
+    delimiter_depth: Cell<u32>,
+    /// How the current source line's text is printed (see `Raw`).
+    raw_text: Cell<Raw>,
+    /// Per code span of the current phrasing content (by span start, sorted):
+    /// the backtick run lengths (bit `n - 1` for a run of `n`) that are literal text before it;
+    /// its fence must avoid them.
+    code_span_literal_runs: RefCell<Vec<(u32, u64)>>,
+    /// The current phrasing content's opaque source spans
+    /// (code spans, HTML, autolinks, math, liquid, wiki links, link labels and titles),
+    /// in source order; `true` marks code spans. Wrapping never cuts inside one.
+    /// Both tables are refilled by every `inline::collect_phrasing`.
+    opaque_spans: RefCell<Vec<(Span, bool)>>,
+    /// Emphasis markers are printed as written: normalizing them would change what pairs.
+    literal_markers: Cell<bool>,
+}
+
+/// Whether text is printed as written, newlines included.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Raw {
+    #[default]
+    No,
+    /// Inside a paragraph where wrapping could form a wiki link (`[[` ... `]]` across texts).
+    Text,
+    /// On a dialect shape line, where emphasis markers stay as written too.
+    Line,
+}
+
+/// What a list's descendants need to know about it.
+#[derive(Clone, Copy, Debug)]
+pub struct ListFrame {
+    /// The list prints the alternate marker (`*` / `)`), and its thematic breaks `---` instead of `***`.
+    pub alternate_marker: bool,
+    /// Prettier's `isAligned`; an unaligned ancestor makes every descendant list unaligned.
+    pub aligned: bool,
+}
+
+impl<'a> MarkdownFormatContext<'a> {
+    pub fn new(options: MarkdownFormatOptions, source_code: &'a str, blanks: &'a [Span]) -> Self {
+        Self {
+            options,
+            source_text: SourceText::new(source_code),
+            blanks,
+            lists: RefCell::new(Vec::new()),
+            no_wrap_depth: Cell::new(0),
+            emphasis_depth: Cell::new(0),
+            delimiter_depth: Cell::new(0),
+            raw_text: Cell::new(Raw::No),
+            code_span_literal_runs: RefCell::new(Vec::new()),
+            opaque_spans: RefCell::new(Vec::new()),
+            literal_markers: Cell::new(false),
+        }
+    }
+
+    /// Returns the source text with the arena lifetime (vs the trait's borrow-elided `&str`).
+    /// Slices taken via this method carry the `'a` lifetime,
+    /// so they don't have to be re-allocated for `text(...)`.
+    pub fn source_text(&self) -> SourceText<'a> {
+        self.source_text
+    }
+
+    pub fn slice(&self, span: Span) -> &'a str {
+        self.source_text.slice_range(span.start, span.end)
+    }
+
+    /// Whether a logical blank line lies between two sibling spans.
+    ///
+    /// Prettier compares `previous.position.end.line + 1 < node.position.start.line`;
+    /// the parser's blank table answers the same question without line numbers,
+    /// and already ignores lines inside fenced blocks.
+    pub fn has_blank_between(&self, prev_end: u32, next_start: u32) -> bool {
+        // A blank that starts where the previous node ends is on that node's last line
+        // (a blockquote's bare `>` line), not a line between the two.
+        let i = self.blanks.partition_point(|blank| blank.start <= prev_end);
+        self.blanks.get(i).is_some_and(|blank| blank.start < next_start)
+    }
+
+    pub fn lists(&self) -> &RefCell<Vec<ListFrame>> {
+        &self.lists
+    }
+
+    pub fn no_wrap_depth(&self) -> &Cell<u32> {
+        &self.no_wrap_depth
+    }
+
+    pub fn emphasis_depth(&self) -> &Cell<u32> {
+        &self.emphasis_depth
+    }
+
+    pub fn delimiter_depth(&self) -> &Cell<u32> {
+        &self.delimiter_depth
+    }
+
+    pub fn raw_text(&self) -> &Cell<Raw> {
+        &self.raw_text
+    }
+
+    pub fn code_span_literal_runs(&self) -> &RefCell<Vec<(u32, u64)>> {
+        &self.code_span_literal_runs
+    }
+
+    pub fn opaque_spans(&self) -> &RefCell<Vec<(Span, bool)>> {
+        &self.opaque_spans
+    }
+
+    pub fn literal_markers(&self) -> &Cell<bool> {
+        &self.literal_markers
+    }
+}
+
+impl FormatContext for MarkdownFormatContext<'_> {
+    type Options = MarkdownFormatOptions;
+
+    fn options(&self) -> &Self::Options {
+        &self.options
+    }
+
+    fn source_code(&self) -> &str {
+        &self.source_text
+    }
+}
diff --git a/crates/oxc_formatter_markdown/src/format.rs b/crates/oxc_formatter_markdown/src/format.rs
new file mode 100644
index 0000000000..0bdd9b0295
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/format.rs
@@ -0,0 +1,119 @@
+use oxc_allocator::Allocator;
+use oxc_diagnostics::OxcDiagnostic;
+use oxc_formatter_core::{
+    Buffer, Document, EmbeddedIr, FormatSession, FormatState, Formatted, Formatter, VecBuffer,
+    builders::{hard_line_break, text},
+    write,
+};
+use oxc_markdown_parser::{Parser, Span, ast::Root};
+
+use crate::{context::MarkdownFormatContext, options::MarkdownFormatOptions, print};
+
+/// Parse `source_text` as a Markdown document and build its formatter IR.
+///
+/// # Errors
+/// Returns an [`OxcDiagnostic`] when the parser reports a diagnostic.
+/// CommonMark has no syntax errors, so markdown mode only fails on input-level limits;
+/// MDX mode (not wired yet) will add real syntax errors.
+pub fn format<'a>(
+    allocator: &'a Allocator,
+    source_text: &str,
+    options: MarkdownFormatOptions,
+) -> Result<Formatted<'a, MarkdownFormatContext<'a>>, OxcDiagnostic> {
+    let parsed = parse_for_format(allocator, source_text)?;
+    let context = MarkdownFormatContext::new(options, parsed.source, parsed.blanks);
+    let mut state = FormatState::new(context, allocator);
+    let mut buffer = VecBuffer::new(&mut state);
+    let f = &mut Formatter::new(&mut buffer);
+    if parsed.has_bom {
+        write!(f, text("\u{feff}"));
+    }
+    // Prettier prints an empty document as the empty string, not `\n`.
+    if !parsed.root.children.is_empty() {
+        print::write_root(parsed.root, f);
+        // POSIX convention: every formatted file ends with a newline.
+        write!(f, hard_line_break());
+    }
+    let elements = buffer.into_vec();
+    Ok(Formatted::new(Document::new(elements, Vec::new()), state.into_context()))
+}
+
+/// [`parse_for_format`] output: the AST, plus the envelope [`format()`] prints around it.
+pub struct ParsedMarkdown<'a> {
+    pub root: &'a Root<'a>,
+    /// Every logical blank line, in source order.
+    pub blanks: &'a [Span],
+    /// Normalized arena source every span indexes into.
+    pub source: &'a str,
+    has_bom: bool,
+}
+
+/// Parse `source_text` the way the formatter does, for callers that inspect the AST
+/// (e.g. a harness comparing what the source held against the formatted output).
+///
+/// [`format()`] goes through this too, so what a caller sees is exactly what gets formatted.
+/// Owns the BOM split and `\r` normalization.
+///
+/// # Errors
+/// Same as [`format()`].
+pub fn parse_for_format<'a>(
+    allocator: &'a Allocator,
+    source_text: &str,
+) -> Result<ParsedMarkdown<'a>, OxcDiagnostic> {
+    let (has_bom, source_text) = oxc_formatter_core::spec::split_bom(source_text);
+    let (root, source, blanks) = parse_root(allocator, source_text)?;
+    Ok(ParsedMarkdown { root, blanks, source, has_bom })
+}
+
+/// Parse `source_text` and build the formatter IR for embedding into another
+/// formatter's document (dispatcher path, e.g. a ` ```md ` fence inside a JSDoc comment).
+///
+/// Unlike [`format()`], this:
+/// - allocates from the session's shared arena and `GroupId` space, so the IR lives as long as the parent's document
+/// - emits neither a BOM nor the trailing newline
+///
+/// # Errors
+/// Same as [`format()`].
+pub fn format_to_ir<'a>(
+    session: &FormatSession<'a>,
+    source_text: &str,
+    options: MarkdownFormatOptions,
+) -> Result<EmbeddedIr<'a>, OxcDiagnostic> {
+    let allocator = session.allocator();
+    let (root, source, blanks) = parse_root(allocator, source_text)?;
+
+    let context = MarkdownFormatContext::new(options, source, blanks);
+    let mut state = FormatState::new_with_session(context, session.clone());
+    let mut buffer = VecBuffer::new(&mut state);
+    // No BOM, no final newline: the parent document owns the surrounding layout.
+    print::write_root(root, &mut Formatter::new(&mut buffer));
+
+    // Markdown never collects Tailwind classes.
+    Ok(EmbeddedIr { ir: buffer.into_vec(), tailwind_classes: Vec::new() })
+}
+
+/// Parse the source into the AST, bailing out on any diagnostic.
+///
+/// Copies the source into the arena so every slice taken from it carries `'a`.
+/// Entries own the BOM strip; this layer assumes BOM-free input (see [`oxc_formatter_core::spec::split_bom`]).
+fn parse_root<'a>(
+    allocator: &'a Allocator,
+    source_text: &str,
+) -> Result<(&'a Root<'a>, &'a str, &'a [Span]), OxcDiagnostic> {
+    // Normalize line endings BEFORE parsing:
+    // the printer slices verbatim text from the source in many places (html, code, liquid, math),
+    // and the IR forbids `\r`.
+    let source_text = oxc_formatter_core::normalize_newlines(source_text, ['\r']);
+    let source: &'a str = allocator.alloc_str(&source_text);
+
+    let ret = Parser::new(allocator, source).parse();
+    if let Some(diagnostic) = ret.diagnostics.first() {
+        return Err(OxcDiagnostic::error(format!("Syntax error: {diagnostic}"))
+            .with_label(oxc_span::Span::new(diagnostic.span.start, diagnostic.span.end)));
+    }
+
+    let root = allocator.alloc(ret.root);
+    let blanks: &'a [Span] = allocator.alloc_slice_copy(&ret.blanks);
+
+    Ok((root, source, blanks))
+}
diff --git a/crates/oxc_formatter_markdown/src/lib.rs b/crates/oxc_formatter_markdown/src/lib.rs
new file mode 100644
index 0000000000..b0935b52de
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/lib.rs
@@ -0,0 +1,26 @@
+//! Markdown formatter built on top of `oxc_formatter_core`.
+//!
+//! Parses with `oxc-markdown-parser`
+//! (CommonMark + GFM + Prettier's extensions, a span-faithful AST whose style facts are first-class fields)
+//! and prints Prettier-compatible output.
+//!
+//! ```ignore
+//! use oxc_allocator::Allocator;
+//! use oxc_formatter_markdown::{MarkdownFormatOptions, format};
+//!
+//! let allocator = Allocator::new();
+//! let formatted = format(&allocator, "#  Title", MarkdownFormatOptions::default()).unwrap();
+//! let out = formatted.print().unwrap().into_code();
+//! assert_eq!(out, "# Title\n");
+//! ```
+
+mod context;
+mod format;
+mod options;
+mod print;
+
+pub use crate::{
+    context::MarkdownFormatContext,
+    format::{ParsedMarkdown, format, format_to_ir, parse_for_format},
+    options::{MarkdownFormatOptions, ProseWrap, SingleQuote},
+};
diff --git a/crates/oxc_formatter_markdown/src/options.rs b/crates/oxc_formatter_markdown/src/options.rs
new file mode 100644
index 0000000000..57115cf572
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/options.rs
@@ -0,0 +1,92 @@
+use oxc_formatter_core::{
+    CoreFormatOptions, FormatOptions, IndentStyle, IndentWidth, LineEnding, LineWidth,
+};
+
+/// Format options for Markdown.
+///
+/// Prettier's `markdown` language consumes the shared layout options plus
+/// `proseWrap` and `singleQuote` (link / image / definition titles).
+#[derive(Debug, Default, Clone, Copy, Eq, PartialEq)]
+pub struct MarkdownFormatOptions {
+    pub indent_style: IndentStyle,
+    pub indent_width: IndentWidth,
+    pub line_width: LineWidth,
+    pub line_ending: LineEnding,
+    /// How paragraph text is re-flowed. Mirrors Prettier's `proseWrap`.
+    pub prose_wrap: ProseWrap,
+    /// Preferred quote for re-quotable titles. Mirrors Prettier's `singleQuote`.
+    pub single_quote: SingleQuote,
+}
+
+/// How paragraph text is re-flowed.
+/// Mirrors Prettier's `proseWrap`.
+#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
+pub enum ProseWrap {
+    /// Keep the source's line structure (default).
+    #[default]
+    Preserve,
+    /// Fold lines to fit the print width.
+    Always,
+    /// Collapse each paragraph onto a single line.
+    Never,
+}
+
+/// Whether `'` is the preferred quote when a title can be re-quoted freely.
+#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
+pub struct SingleQuote(bool);
+
+impl SingleQuote {
+    pub fn value(self) -> bool {
+        self.0
+    }
+}
+
+impl From<bool> for SingleQuote {
+    fn from(value: bool) -> Self {
+        Self(value)
+    }
+}
+
+impl MarkdownFormatOptions {
+    /// The quote byte (`b'"'` / `b'\''`) to enclose a title whose body is `inner`:
+    /// start from the configured preference (`singleQuote`) and flip to the alternate when that reduces escapes
+    /// (i.e. when the preferred quote occurs more often in `inner` than the alternate).
+    pub fn preferred_quote(self, inner: &str) -> u8 {
+        let (preferred, alternate) =
+            if self.single_quote.value() { (b'\'', b'"') } else { (b'"', b'\'') };
+        let (mut preferred_count, mut alternate_count) = (0u32, 0u32);
+        for byte in inner.bytes() {
+            if byte == preferred {
+                preferred_count += 1;
+            } else if byte == alternate {
+                alternate_count += 1;
+            }
+        }
+        if preferred_count > alternate_count { alternate } else { preferred }
+    }
+}
+
+impl FormatOptions for MarkdownFormatOptions {
+    fn indent_style(&self) -> IndentStyle {
+        self.indent_style
+    }
+
+    fn indent_width(&self) -> IndentWidth {
+        self.indent_width
+    }
+
+    fn line_width(&self) -> LineWidth {
+        self.line_width
+    }
+
+    fn line_ending(&self) -> LineEnding {
+        self.line_ending
+    }
+
+    fn apply_core(&mut self, core: CoreFormatOptions) {
+        self.indent_style = core.indent_style;
+        self.indent_width = core.indent_width;
+        self.line_width = core.line_width;
+        self.line_ending = core.line_ending;
+    }
+}
diff --git a/crates/oxc_formatter_markdown/src/print/block.rs b/crates/oxc_formatter_markdown/src/print/block.rs
new file mode 100644
index 0000000000..c1f884b745
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/block.rs
@@ -0,0 +1,390 @@
+//! Block dispatch and the blank-line policy between siblings.
+
+use oxc_formatter_core::{
+    Buffer,
+    builders::{
+        align, exact_line_breaks, group, hard_line_break, literal_line_break, mark_as_root,
+        soft_line_break_or_space, space, text, token,
+    },
+    format_args,
+    spec::is_suppression_marker,
+    write,
+};
+use oxc_markdown_parser::ast::{
+    Block, FootnoteDefinition, Heading, HeadingKind, HtmlBlock, Liquid, MathBlock,
+};
+
+use crate::{context::MarkdownFormatContext, options::ProseWrap};
+
+use super::{
+    MarkdownFormatter, blockquote, code, format_with, inline, join_pieces, line_shape, link, list,
+    table, with_depth, write_indented_lines, write_lines, write_verbatim,
+};
+
+/// What contains the blocks being written; the gap policy depends on it.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Parent {
+    Root,
+    /// `loose`: spread, or a blank line before the next item.
+    /// `after_checkbox`: the block follows a task checkbox on its line.
+    ListItem {
+        loose: bool,
+        after_checkbox: bool,
+    },
+    /// Blockquote or container directive.
+    Container,
+}
+
+/// Emits sibling blocks with a blank line between them, except where one line break is the rule
+/// (tight list items, adjacent HTML, consecutive definitions, ...).
+///
+/// `<!-- prettier-ignore -->` (or `oxfmt-ignore`) freezes the next block;
+/// `-start` / `-end` pairs freeze the range between them.
+pub fn write_blocks<'a>(
+    blocks: &'a [Block<'a>],
+    parent: Parent,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) {
+    let mut index = 0;
+    while index < blocks.len() {
+        let block = &blocks[index];
+        if index > 0 {
+            write_gap(blocks, index, parent, f);
+        }
+
+        // `<!-- prettier-ignore-start -->` ... `<!-- prettier-ignore-end -->`: the range is source text.
+        // Only at the document root; nested, the comments are plain HTML.
+        if parent == Parent::Root
+            && let Some(end) = ignore_range_end(blocks, index, f)
+        {
+            let source = f.context().source_text();
+            let start_comment = block.span();
+            let end_comment = blocks[end].span();
+            write_verbatim(start_comment, f);
+            write!(f, text(source.slice_range(start_comment.end, end_comment.start)));
+            write_verbatim(end_comment, f);
+            index = end + 1;
+            continue;
+        }
+
+        write_block(block, blocks, index, parent, f);
+        index += 1;
+    }
+}
+
+pub fn write_gap(
+    siblings: &[Block<'_>],
+    index: usize,
+    parent: Parent,
+    f: &mut MarkdownFormatter<'_, '_>,
+) {
+    super::write_gap(double_gap(siblings, index, parent, f), f);
+}
+
+/// Whether `siblings[index]` gets a blank line before it.
+fn double_gap(
+    siblings: &[Block<'_>],
+    index: usize,
+    parent: Parent,
+    f: &MarkdownFormatter<'_, '_>,
+) -> bool {
+    let (previous, node) = (&siblings[index - 1], &siblings[index]);
+    let ctx = f.context();
+    let adjacent = !ctx.has_blank_between(previous.span().end, node.span().start);
+
+    // ```
+    // [a]: b
+    // [c]: d
+    // Text
+    // ===
+    // ```
+    // mdast starts the heading at the first definition (they were the heading paragraph's first lines),
+    // and Prettier keeps them together only when that start lies on an earlier line than the last definition's end:
+    // the run has two definitions, or its one definition spans lines.
+    if adjacent
+        && matches!(previous, Block::Definition(_))
+        && matches!(node, Block::Heading(h) if matches!(h.kind, HeadingKind::Setext { .. }))
+    {
+        let after_definition = index >= 2
+            && matches!(siblings[index - 2], Block::Definition(_))
+            && !ctx.has_blank_between(siblings[index - 2].span().end, previous.span().start);
+        let multi_line =
+            ctx.source_text().bytes_contain(previous.span().start, previous.span().end, b'\n');
+        return !after_definition && !multi_line;
+    }
+
+    // A nested list after a paragraph / code keeps its blank line (prettier#17746)
+    if matches!(node, Block::List(_))
+        && matches!(parent, Parent::ListItem { .. })
+        && matches!(previous, Block::CodeBlock(_) | Block::Paragraph(_))
+        && !adjacent
+    {
+        return true;
+    }
+
+    let is_sibling_node = matches!((previous, node), (Block::Definition(_), Block::Definition(_)));
+    let in_tight_list_item = match parent {
+        Parent::ListItem { loose, .. } => matches!(node, Block::List(_)) || !loose,
+        _ => false,
+    };
+    let prev_is_ignore = ignore_kind(previous, f) == Some(IgnoreKind::Next);
+    let html_after_html = matches!((previous, node), (Block::HtmlBlock(_), Block::HtmlBlock(_)));
+    // A type 7 HTML block can only follow a paragraph without a blank line as a lazy line of a container
+    // (a micromark quirk, parser DIVERGENCES);
+    // printed with the container's prefix it needs the blank line to stay a block.
+    // Prettier prints it adjacent, where it becomes paragraph text.
+    let html_after_paragraph =
+        matches!((previous, node), (Block::Paragraph(_), Block::HtmlBlock(h)) if h.kind != 7);
+    let liquid = matches!(previous, Block::Liquid(_)) || matches!(node, Block::Liquid(_));
+    // The rest of a paragraph a definition was split from,
+    // whose first line would open a block at a block start (`<Badge />`):
+    // kept on the definition's next line, a continuation as in the source
+    let remainder_after_definition = || {
+        matches!((previous, node),
+            (Block::Definition(_), Block::Paragraph(p)) if line_shape::first_line_opens_block(&p.children, f))
+    };
+
+    !(is_sibling_node
+        || in_tight_list_item
+        || prev_is_ignore
+        || (adjacent
+            && (html_after_html || html_after_paragraph || liquid || remainder_after_definition())))
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum IgnoreKind {
+    Next,
+    Start,
+    End,
+}
+
+/// `<!-- prettier-ignore -->` / `<!-- oxfmt-ignore -->` and their `-start` / `-end` forms as a whole HTML block.
+/// Asked several times per block, so it bails on the first byte before joining anything.
+fn ignore_kind(block: &Block<'_>, f: &MarkdownFormatter<'_, '_>) -> Option<IgnoreKind> {
+    let Block::HtmlBlock(html) = block else { return None };
+
+    let source = f.context().source_text().as_str();
+    let (first, last) = (html.lines.first()?, html.lines.last()?);
+    if !first.span.slice(source).starts_with("<!--") || !last.span.slice(source).ends_with("-->") {
+        return None;
+    }
+    let value = join_pieces(&html.lines, f);
+    let inner = value.strip_prefix("<!--")?.strip_suffix("-->")?.trim();
+    if is_suppression_marker(inner) {
+        return Some(IgnoreKind::Next);
+    }
+    if let Some(marker) = inner.strip_suffix("-start")
+        && is_suppression_marker(marker)
+    {
+        return Some(IgnoreKind::Start);
+    }
+    if let Some(marker) = inner.strip_suffix("-end")
+        && is_suppression_marker(marker)
+    {
+        return Some(IgnoreKind::End);
+    }
+    None
+}
+
+/// The index of the `-end` comment closing an ignore range opened at `index`, if any.
+fn ignore_range_end(
+    blocks: &[Block<'_>],
+    index: usize,
+    f: &MarkdownFormatter<'_, '_>,
+) -> Option<usize> {
+    if ignore_kind(&blocks[index], f) != Some(IgnoreKind::Start) {
+        return None;
+    }
+    (index + 1..blocks.len()).find(|&i| ignore_kind(&blocks[i], f) == Some(IgnoreKind::End))
+}
+
+/// `<!-- prettier-ignore -->` right before `siblings[index]`: the block is printed as source text.
+pub fn is_ignored(siblings: &[Block<'_>], index: usize, f: &MarkdownFormatter<'_, '_>) -> bool {
+    index > 0 && ignore_kind(&siblings[index - 1], f) == Some(IgnoreKind::Next)
+}
+
+/// `siblings[index]` is `block`; some blocks look at their neighbors.
+pub fn write_block<'a>(
+    block: &'a Block<'a>,
+    siblings: &'a [Block<'a>],
+    index: usize,
+    parent: Parent,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) {
+    if is_ignored(siblings, index, f) {
+        write_verbatim(block.span(), f);
+        return;
+    }
+    match block {
+        Block::Paragraph(p) => {
+            let parent = inline::InlineParent {
+                paragraph: true,
+                first_in_container: parent == Parent::Container && index == 0,
+                after_checkbox: matches!(parent, Parent::ListItem { after_checkbox: true, .. }),
+                ..inline::InlineParent::default()
+            };
+            inline::write_inlines(&p.children, parent, f);
+        }
+        Block::Heading(h) => write_heading(h, f),
+        Block::ThematicBreak(_) => write_thematic_break(index, parent, f),
+        Block::CodeBlock(c) => code::write_code_block(c, f),
+        Block::HtmlBlock(h) => {
+            let is_last_in_root = parent == Parent::Root && index + 1 == siblings.len();
+            write_html_block(h, is_last_in_root, f);
+        }
+        Block::Blockquote(q) => blockquote::write_blockquote(q, f),
+        Block::List(l) => list::write_list(l, siblings, index, f),
+        Block::Definition(d) => link::write_definition(d, f),
+        Block::MathBlock(m) => write_math_block(m, f),
+        Block::Liquid(l) => write_liquid_block(l, f),
+        Block::ContainerDirective(d) => {
+            // Fence lines are verbatim (dialects disagree on their grammar); children are markdown
+            write_verbatim(d.opening, f);
+            if !d.children.is_empty() {
+                write!(f, hard_line_break());
+                write_blocks(&d.children, Parent::Container, f);
+            }
+            if let Some(closing) = d.closing {
+                write!(f, hard_line_break());
+                write_verbatim(closing, f);
+            }
+        }
+        Block::Table(t) => table::write_table(t, f),
+        Block::FootnoteDefinition(d) => write_footnote_definition(d, f),
+        // MDX stays verbatim
+        Block::MdxEsm(_) | Block::MdxExpression(_) | Block::MdxJsx(_) => {
+            write_verbatim(block.span(), f);
+        }
+    }
+}
+
+/// ATX headings normalize to `#`s + one space;
+/// setext headings keep their underline verbatim (length included).
+fn write_heading<'a>(heading: &'a Heading<'a>, f: &mut MarkdownFormatter<'_, 'a>) {
+    match &heading.kind {
+        HeadingKind::Atx => {
+            const HASHES: &str = "######";
+            // `space` dies at the line break, so an empty heading is just its `#`s
+            write!(f, [text(&HASHES[..usize::from(heading.level)]), space()]);
+            // An ATX heading never wraps
+            with_depth(f, MarkdownFormatContext::no_wrap_depth, |f| {
+                inline::write_inlines(&heading.children, inline::InlineParent::default(), f);
+            });
+        }
+        HeadingKind::Setext { underline, .. } => {
+            // Multi-line like a paragraph: its source lines get the paragraph's line rules
+            let parent =
+                inline::InlineParent { paragraph: true, ..inline::InlineParent::default() };
+            inline::write_inlines(&heading.children, parent, f);
+            let raw = f.context().slice(*underline);
+            write!(f, [hard_line_break(), text(raw.trim_end())]);
+        }
+    }
+}
+
+/// `[^label]: ` + content.
+/// A lone paragraph stays on the label's line under `never` (and under `preserve` when it is one source line);
+/// otherwise the content is aligned by 4 and the first block moves to its own line when it does not fit
+/// (or is multi-line).
+fn write_footnote_definition<'a>(
+    def: &'a FootnoteDefinition<'a>,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) {
+    write!(f, [token("[^"), text(f.context().slice(def.label)), token("]:")]);
+    let children = &def.children;
+    let inline = match children.as_slice() {
+        [Block::Paragraph(p)] => match f.options().prose_wrap {
+            ProseWrap::Never => true,
+            // Prettier asks whether the source paragraph is one line;
+            // asking whether it prints as one keeps the answer stable across passes
+            // (a line break joined away would flip it).
+            ProseWrap::Preserve => !inline::keeps_a_line_break(&p.children, f),
+            ProseWrap::Always => false,
+        },
+        _ => false,
+    };
+    if inline {
+        write!(f, space());
+        write_blocks(children, Parent::Container, f);
+        return;
+    }
+    let parent = Parent::Container;
+    write!(
+        f,
+        align(
+            4,
+            &mark_as_root(&format_with(|f| {
+                let first = format_with(|f| write_block(&children[0], children, 0, parent, f));
+                write!(f, group(&format_args!(soft_line_break_or_space(), first)));
+                for index in 1..children.len() {
+                    write_gap(children, index, parent, f);
+                    write_block(&children[index], children, index, parent, f);
+                }
+            }))
+        )
+    );
+}
+
+/// `---`, except inside a list
+/// (alternating with `***` by the list's sibling parity so the marker never collides with a bullet)
+/// and as the first block of the document (`***`, so it never reads as front matter).
+fn write_thematic_break(index: usize, parent: Parent, f: &mut MarkdownFormatter<'_, '_>) {
+    let frame = f.context().lists().borrow().last().copied();
+    let star = match frame {
+        None => index == 0 && parent == Parent::Root,
+        Some(frame) => !frame.alternate_marker,
+    };
+    write!(f, token(if star { "***" } else { "---" }));
+}
+
+/// HTML blocks are verbatim, line by line.
+///
+/// Comments re-indent at the current indention;
+/// anything else goes through literal lines anchored at the current indention, which never trim.
+fn write_html_block<'a>(
+    html: &'a HtmlBlock<'a>,
+    is_last_in_root: bool,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) {
+    let mut value = join_pieces(&html.lines, f);
+    if is_last_in_root {
+        value = value.trim_end_matches(['\n', ' ', '\t']);
+    }
+    if is_html_comment(value) {
+        write_indented_lines(value, f);
+        return;
+    }
+    // micromark keeps the closing line ending as content in a few shapes (`HtmlBlock::trailing_newline`);
+    // Prettier prints it, and the block gains a line on every pass. It is not printed.
+    write!(
+        f,
+        mark_as_root(&format_with(|f| write_lines(value.split('\n'), literal_line_break(), f)))
+    );
+}
+
+/// `$$` fences are normalized; the content is verbatim.
+fn write_math_block<'a>(math: &'a MathBlock<'a>, f: &mut MarkdownFormatter<'_, 'a>) {
+    write!(f, token("$$"));
+    if let Some(meta) = math.meta {
+        let raw = f.context().slice(meta);
+        write!(f, [token(" "), text(raw)]);
+    }
+    write!(f, hard_line_break());
+    if !math.lines.is_empty() {
+        write_indented_lines(join_pieces(&math.lines, f), f);
+        // As for code: a trailing blank line must survive
+        // (`hard_line_break` would print nothing after it)
+        write!(f, exact_line_breaks(1));
+    }
+    write!(f, token("$$"));
+}
+
+/// A `{% %}` / `{{ }}` tag standing alone is verbatim, line by line.
+fn write_liquid_block<'a>(liquid: &'a Liquid<'a>, f: &mut MarkdownFormatter<'_, 'a>) {
+    write_indented_lines(join_pieces(&liquid.pieces, f), f);
+}
+
+/// Prettier's comment test for HTML values: `<!--` ... `-->` as the whole value.
+pub fn is_html_comment(value: &str) -> bool {
+    value.starts_with("<!--") && value.ends_with("-->")
+}
diff --git a/crates/oxc_formatter_markdown/src/print/blockquote.rs b/crates/oxc_formatter_markdown/src/print/blockquote.rs
new file mode 100644
index 0000000000..445f80ea7f
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/blockquote.rs
@@ -0,0 +1,22 @@
+//! Blockquotes: `> ` before the first line, then before every line the body breaks into
+//! (`prefix_align`; a blank line inside prints as `>`).
+
+use oxc_formatter_core::{
+    Buffer,
+    builders::{mark_as_root, prefix_align},
+    write,
+};
+use oxc_markdown_parser::ast::Blockquote;
+
+use super::{MarkdownFormatter, block, format_with};
+
+pub fn write_blockquote<'a>(quote: &'a Blockquote<'a>, f: &mut MarkdownFormatter<'_, 'a>) {
+    // An empty one is `>`: the printer never trims a trailing space
+    if quote.children.is_empty() {
+        write!(f, ">");
+        return;
+    }
+    let body = format_with(|f| block::write_blocks(&quote.children, block::Parent::Container, f));
+    // The prefixed column is the root that verbatim continuation lines return to
+    write!(f, ["> ", prefix_align(&"> ", &mark_as_root(&body))]);
+}
diff --git a/crates/oxc_formatter_markdown/src/print/cjk.rs b/crates/oxc_formatter_markdown/src/print/cjk.rs
new file mode 100644
index 0000000000..e21a6c7af6
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/cjk.rs
@@ -0,0 +1,181 @@
+//! Word kinds for the CJK line-breaking rules (Prettier's `splitText` / `printWhitespace`).
+//!
+//! A whitespace-delimited word is split into runs of non-CJK characters
+//! and single CJK characters (a variation selector stays with its base);
+//! only the edge runs matter to the printer,
+//! and the split as a whole feeds the "does this sentence put spaces around CJ text" statistic.
+//!
+//! The tables are Prettier's own character classes
+//! (`constants.evaluate.js`: `cjk-regex` + Script_Extensions / General_Category for CJK,
+//! ASCII punctuation + `\p{P}` (+ U+3000, U+FF5E) for punctuation, `\p{Script_Extensions=Hangul}` for Korean),
+//! enumerated with Node 26 (Unicode 17).
+//! Regenerate by testing every code point against those regexes and collapsing the hits into ranges.
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Kind {
+    NonCjk,
+    /// Chinese or Japanese letter: no spaces between words, a line break is not a space.
+    CjLetter,
+    /// Korean letter: words are space-separated, as in Latin script.
+    KLetter,
+    CjkPunctuation,
+}
+
+impl Kind {
+    pub fn is_cj(self) -> bool {
+        matches!(self, Kind::CjLetter | Kind::CjkPunctuation)
+    }
+}
+
+/// The run at one end of a word, as the whitespace next to it sees it.
+#[derive(Clone, Copy, Debug)]
+pub struct Edge {
+    pub kind: Kind,
+    /// The run's character on the whitespace side.
+    pub ch: char,
+    /// That character is punctuation (a CJK punctuation run always is).
+    pub punctuation: bool,
+}
+
+/// The kinds of a word's runs, in order.
+pub fn kinds(word: &str) -> impl Iterator<Item = Kind> + '_ {
+    runs(word).map(|(_, kind)| kind)
+}
+
+/// The word's first and last run, as edges.
+pub fn edges(word: &str) -> Option<(Edge, Edge)> {
+    let mut it = runs(word);
+    let (first_run, first_kind) = it.next()?;
+    let (last_run, last_kind) = it.last().unwrap_or((first_run, first_kind));
+    let first_ch = first_run.chars().next()?;
+    let last_ch = last_run.chars().next_back()?;
+    let edge = |kind: Kind, ch: char| Edge {
+        kind,
+        ch,
+        punctuation: kind == Kind::CjkPunctuation || is_punctuation(ch),
+    };
+    Some((edge(first_kind, first_ch), edge(last_kind, last_ch)))
+}
+
+/// Splits a word into runs: each CJK character (plus a following variation selector) on its own,
+/// non-CJK characters together.
+fn runs(word: &str) -> impl Iterator<Item = (&str, Kind)> {
+    let mut rest = word;
+    std::iter::from_fn(move || {
+        let c = rest.chars().next()?;
+        let (len, kind) = if is_cjk(c) {
+            let mut len = c.len_utf8();
+            if let Some(vs) = rest[len..].chars().next()
+                && is_variation_selector(vs)
+            {
+                len += vs.len_utf8();
+            }
+            let kind = if is_punctuation(c) {
+                Kind::CjkPunctuation
+            } else if is_hangul(c) {
+                Kind::KLetter
+            } else {
+                Kind::CjLetter
+            };
+            (len, kind)
+        } else {
+            let len = rest.find(is_cjk).unwrap_or(rest.len());
+            (len, Kind::NonCjk)
+        };
+        let (run, tail) = rest.split_at(len);
+        rest = tail;
+        Some((run, kind))
+    })
+}
+
+fn is_variation_selector(c: char) -> bool {
+    matches!(u32::from(c), 0xFE00..=0xFE0F | 0xE0100..=0xE01EF)
+}
+
+pub fn is_cjk(c: char) -> bool {
+    !c.is_ascii() && in_ranges(CJK, c)
+}
+
+fn is_hangul(c: char) -> bool {
+    in_ranges(HANGUL, c)
+}
+
+/// ASCII punctuation, U+3000, U+FF5E, or Unicode general category P.
+pub fn is_punctuation(c: char) -> bool {
+    if c.is_ascii() {
+        return c.is_ascii_punctuation();
+    }
+    matches!(c, '\u{3000}' | '\u{FF5E}') || in_ranges(PUNCTUATION, c)
+}
+
+fn in_ranges(ranges: &[(u32, u32)], c: char) -> bool {
+    let cp = u32::from(c);
+    ranges
+        .binary_search_by(|&(lo, hi)| {
+            if cp < lo {
+                std::cmp::Ordering::Greater
+            } else if cp > hi {
+                std::cmp::Ordering::Less
+            } else {
+                std::cmp::Ordering::Equal
+            }
+        })
+        .is_ok()
+}
+
+#[rustfmt::skip]
+static CJK: &[(u32, u32)] = &[
+    (0x2C7, 0x2C7), (0x2C9, 0x2CB), (0x2D9, 0x2D9), (0x2EA, 0x2EB), (0x305, 0x305), (0x323, 0x323),
+    (0x1100, 0x11FF), (0x2E80, 0x2E99), (0x2E9B, 0x2EF3), (0x2F00, 0x2FD5), (0x2FF0, 0x303F), (0x3041, 0x3096),
+    (0x3099, 0x30FF), (0x3105, 0x312F), (0x3131, 0x318E), (0x3190, 0x4DBF), (0x4E00, 0x9FFF), (0xA700, 0xA707),
+    (0xA960, 0xA97C), (0xAC00, 0xD7A3), (0xD7B0, 0xD7C6), (0xD7CB, 0xD7FB), (0xF900, 0xFA6D), (0xFA70, 0xFAD9),
+    (0xFE10, 0xFE1F), (0xFE30, 0xFE6F), (0xFF00, 0xFFEF), (0x16FE3, 0x16FE3), (0x16FF2, 0x16FF6), (0x1AFF0, 0x1AFF3),
+    (0x1AFF5, 0x1AFFB), (0x1AFFD, 0x1AFFE), (0x1B000, 0x1B122), (0x1B132, 0x1B132), (0x1B150, 0x1B152), (0x1B155, 0x1B155),
+    (0x1B164, 0x1B167), (0x1F200, 0x1F200), (0x1F250, 0x1F251), (0x20000, 0x2A6DF), (0x2A700, 0x2B81D), (0x2B820, 0x2CEAD),
+    (0x2CEB0, 0x2EBE0), (0x2EBF0, 0x2EE5D), (0x2F800, 0x2FA1D), (0x30000, 0x3134A), (0x31350, 0x33479),
+];
+
+#[rustfmt::skip]
+static HANGUL: &[(u32, u32)] = &[
+    (0x1100, 0x11FF), (0x3001, 0x3003), (0x3008, 0x3011), (0x3013, 0x301F), (0x302E, 0x3030), (0x3037, 0x3037),
+    (0x30FB, 0x30FB), (0x3131, 0x318E), (0x3200, 0x321E), (0x3260, 0x327E), (0xA960, 0xA97C), (0xAC00, 0xD7A3),
+    (0xD7B0, 0xD7C6), (0xD7CB, 0xD7FB), (0xFE45, 0xFE46), (0xFF61, 0xFF65), (0xFFA0, 0xFFBE), (0xFFC2, 0xFFC7),
+    (0xFFCA, 0xFFCF), (0xFFD2, 0xFFD7), (0xFFDA, 0xFFDC),
+];
+
+/// Non-ASCII part only.
+#[rustfmt::skip]
+static PUNCTUATION: &[(u32, u32)] = &[
+    (0xA1, 0xA1), (0xA7, 0xA7), (0xAB, 0xAB), (0xB6, 0xB7), (0xBB, 0xBB), (0xBF, 0xBF),
+    (0x37E, 0x37E), (0x387, 0x387), (0x55A, 0x55F), (0x589, 0x58A), (0x5BE, 0x5BE), (0x5C0, 0x5C0),
+    (0x5C3, 0x5C3), (0x5C6, 0x5C6), (0x5F3, 0x5F4), (0x609, 0x60A), (0x60C, 0x60D), (0x61B, 0x61B),
+    (0x61D, 0x61F), (0x66A, 0x66D), (0x6D4, 0x6D4), (0x700, 0x70D), (0x7F7, 0x7F9), (0x830, 0x83E),
+    (0x85E, 0x85E), (0x964, 0x965), (0x970, 0x970), (0x9FD, 0x9FD), (0xA76, 0xA76), (0xAF0, 0xAF0),
+    (0xC77, 0xC77), (0xC84, 0xC84), (0xDF4, 0xDF4), (0xE4F, 0xE4F), (0xE5A, 0xE5B), (0xF04, 0xF12),
+    (0xF14, 0xF14), (0xF3A, 0xF3D), (0xF85, 0xF85), (0xFD0, 0xFD4), (0xFD9, 0xFDA), (0x104A, 0x104F),
+    (0x10FB, 0x10FB), (0x1360, 0x1368), (0x1400, 0x1400), (0x166E, 0x166E), (0x169B, 0x169C), (0x16EB, 0x16ED),
+    (0x1735, 0x1736), (0x17D4, 0x17D6), (0x17D8, 0x17DA), (0x1800, 0x180A), (0x1944, 0x1945), (0x1A1E, 0x1A1F),
+    (0x1AA0, 0x1AA6), (0x1AA8, 0x1AAD), (0x1B4E, 0x1B4F), (0x1B5A, 0x1B60), (0x1B7D, 0x1B7F), (0x1BFC, 0x1BFF),
+    (0x1C3B, 0x1C3F), (0x1C7E, 0x1C7F), (0x1CC0, 0x1CC7), (0x1CD3, 0x1CD3), (0x2010, 0x2027), (0x2030, 0x2043),
+    (0x2045, 0x2051), (0x2053, 0x205E), (0x207D, 0x207E), (0x208D, 0x208E), (0x2308, 0x230B), (0x2329, 0x232A),
+    (0x2768, 0x2775), (0x27C5, 0x27C6), (0x27E6, 0x27EF), (0x2983, 0x2998), (0x29D8, 0x29DB), (0x29FC, 0x29FD),
+    (0x2CF9, 0x2CFC), (0x2CFE, 0x2CFF), (0x2D70, 0x2D70), (0x2E00, 0x2E2E), (0x2E30, 0x2E4F), (0x2E52, 0x2E5D),
+    (0x3000, 0x3003), (0x3008, 0x3011), (0x3014, 0x301F), (0x3030, 0x3030), (0x303D, 0x303D), (0x30A0, 0x30A0),
+    (0x30FB, 0x30FB), (0xA4FE, 0xA4FF), (0xA60D, 0xA60F), (0xA673, 0xA673), (0xA67E, 0xA67E), (0xA6F2, 0xA6F7),
+    (0xA874, 0xA877), (0xA8CE, 0xA8CF), (0xA8F8, 0xA8FA), (0xA8FC, 0xA8FC), (0xA92E, 0xA92F), (0xA95F, 0xA95F),
+    (0xA9C1, 0xA9CD), (0xA9DE, 0xA9DF), (0xAA5C, 0xAA5F), (0xAADE, 0xAADF), (0xAAF0, 0xAAF1), (0xABEB, 0xABEB),
+    (0xFD3E, 0xFD3F), (0xFE10, 0xFE19), (0xFE30, 0xFE52), (0xFE54, 0xFE61), (0xFE63, 0xFE63), (0xFE68, 0xFE68),
+    (0xFE6A, 0xFE6B), (0xFF01, 0xFF03), (0xFF05, 0xFF0A), (0xFF0C, 0xFF0F), (0xFF1A, 0xFF1B), (0xFF1F, 0xFF20),
+    (0xFF3B, 0xFF3D), (0xFF3F, 0xFF3F), (0xFF5B, 0xFF5B), (0xFF5D, 0xFF65), (0x10100, 0x10102), (0x1039F, 0x1039F),
+    (0x103D0, 0x103D0), (0x1056F, 0x1056F), (0x10857, 0x10857), (0x1091F, 0x1091F), (0x1093F, 0x1093F), (0x10A50, 0x10A58),
+    (0x10A7F, 0x10A7F), (0x10AF0, 0x10AF6), (0x10B39, 0x10B3F), (0x10B99, 0x10B9C), (0x10D6E, 0x10D6E), (0x10EAD, 0x10EAD),
+    (0x10ED0, 0x10ED0), (0x10F55, 0x10F59), (0x10F86, 0x10F89), (0x11047, 0x1104D), (0x110BB, 0x110BC), (0x110BE, 0x110C1),
+    (0x11140, 0x11143), (0x11174, 0x11175), (0x111C5, 0x111C8), (0x111CD, 0x111CD), (0x111DB, 0x111DB), (0x111DD, 0x111DF),
+    (0x11238, 0x1123D), (0x112A9, 0x112A9), (0x113D4, 0x113D5), (0x113D7, 0x113D8), (0x1144B, 0x1144F), (0x1145A, 0x1145B),
+    (0x1145D, 0x1145D), (0x114C6, 0x114C6), (0x115C1, 0x115D7), (0x11641, 0x11643), (0x11660, 0x1166C), (0x116B9, 0x116B9),
+    (0x1173C, 0x1173E), (0x1183B, 0x1183B), (0x11944, 0x11946), (0x119E2, 0x119E2), (0x11A3F, 0x11A46), (0x11A9A, 0x11A9C),
+    (0x11A9E, 0x11AA2), (0x11B00, 0x11B09), (0x11BE1, 0x11BE1), (0x11C41, 0x11C45), (0x11C70, 0x11C71), (0x11EF7, 0x11EF8),
+    (0x11F43, 0x11F4F), (0x11FFF, 0x11FFF), (0x12470, 0x12474), (0x12FF1, 0x12FF2), (0x16A6E, 0x16A6F), (0x16AF5, 0x16AF5),
+    (0x16B37, 0x16B3B), (0x16B44, 0x16B44), (0x16D6D, 0x16D6F), (0x16E97, 0x16E9A), (0x16FE2, 0x16FE2), (0x1BC9F, 0x1BC9F),
+    (0x1DA87, 0x1DA8B), (0x1E5FF, 0x1E5FF), (0x1E95E, 0x1E95F),
+];
diff --git a/crates/oxc_formatter_markdown/src/print/code.rs b/crates/oxc_formatter_markdown/src/print/code.rs
new file mode 100644
index 0000000000..2f78dcc6b4
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/code.rs
@@ -0,0 +1,67 @@
+//! Code blocks: fences are recomputed (the shortest backtick run the content permits, at least 3),
+//! indented blocks stay indented.
+
+use cow_utils::CowUtils;
+
+use oxc_formatter_core::{
+    Buffer, arena_cow_str,
+    builders::{align, exact_line_breaks, hard_line_break, text, token},
+    write,
+};
+use oxc_markdown_parser::{
+    ast::{CodeBlock, CodeBlockKind},
+    decode,
+};
+
+use super::{
+    MarkdownFormatter, backticks, format_with, join_pieces, max_run, write_indented_lines,
+};
+
+pub fn write_code_block<'a>(code: &'a CodeBlock<'a>, f: &mut MarkdownFormatter<'_, 'a>) {
+    let value: &'a str = join_pieces(&code.lines, f);
+
+    match code.kind {
+        CodeBlockKind::Indented => {
+            write!(
+                f,
+                align(
+                    4,
+                    &format_with(|f| {
+                        write!(f, token("    "));
+                        write_indented_lines(value, f);
+                    })
+                )
+            );
+        }
+        CodeBlockKind::Fenced { lang, meta, .. } => {
+            let (lang, meta) =
+                (lang.map(|s| f.context().slice(s)), meta.map(|s| f.context().slice(s)));
+            // `~~~` fences normalize to backticks, unless the info string has one (only `~~~` allows it)
+            let info_has_backtick = [lang, meta].iter().flatten().any(|part| part.contains('`'));
+            let fence: &'a str = if info_has_backtick {
+                "~~~"
+            } else {
+                arena_cow_str(&backticks((max_run(value, b'`') + 1).max(3)), f)
+            };
+            write!(f, text(fence));
+            // `lang` + one space + `meta`, decoded, the whitespace between them normalized
+            for (i, part) in [lang, meta].into_iter().flatten().enumerate() {
+                if i > 0 {
+                    write!(f, token(" "));
+                }
+                write!(f, text(cooked_info(part, f)));
+            }
+            write!(f, hard_line_break());
+            write_indented_lines(value, f);
+            // A trailing blank line in the content (or an empty block's one empty line) must survive:
+            // `hard_line_break` would see an empty line and print nothing.
+            write!(f, [exact_line_breaks(1), text(fence)]);
+        }
+    }
+}
+
+/// An info string part decoded; a backslash left by decoding is escaped again,
+/// or the next parse would apply it to what it protected (`\\[` printed as `\[` decodes to `[`).
+fn cooked_info<'a>(part: &'a str, f: &MarkdownFormatter<'_, 'a>) -> &'a str {
+    f.allocator().alloc_str(&decode::decode(part, true).cow_replace('\\', "\\\\"))
+}
diff --git a/crates/oxc_formatter_markdown/src/print/escape.rs b/crates/oxc_formatter_markdown/src/print/escape.rs
new file mode 100644
index 0000000000..e28899f956
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/escape.rs
@@ -0,0 +1,113 @@
+//! Escapes, the only places text is changed (AGENTS.md "Escaping"): pure functions over one word.
+
+use std::borrow::Cow;
+
+use oxc_markdown_parser::attention;
+
+/// An odd run of `\` ends the word.
+pub fn ends_with_unescaped_backslash(word: &str) -> bool {
+    word.bytes().rev().take_while(|&b| b == b'\\').count() % 2 == 1
+}
+
+/// `^(?:=+|-+)$`
+pub fn is_fake_setext_underline(word: &str) -> bool {
+    !word.is_empty() && (word.bytes().all(|b| b == b'=') || word.bytes().all(|b| b == b'-'))
+}
+
+/// A word inside emphasis / strong, with the runs that could end it escaped.
+///
+/// `prev` / `next` are the characters around the word within its text;
+/// `None` at the text edges, where neighbours across nodes are not consulted (as in Prettier) and nothing is escaped.
+pub fn print_delimited_word<'a>(
+    word: &'a str,
+    escape_leading: bool,
+    autolink_stretch: usize,
+    prev: Option<char>,
+    next: Option<char>,
+) -> Cow<'a, str> {
+    if !word.contains(['*', '_']) {
+        return Cow::Borrowed(word);
+    }
+    let text: Cow<'a, str> =
+        if escape_leading { Cow::Owned(format!("\\{word}")) } else { Cow::Borrowed(word) };
+    escape_delimiter_runs(text, autolink_stretch, prev, next)
+}
+
+/// Escapes every `*` / `_` run that could open or close emphasis where it stands, character by character
+/// (a single backslash only shortens the run, and the rest can still pair: Prettier's `\***`).
+///
+/// One rule for every run,
+/// Prettier's regex scan skips a run right after another run's following character;
+/// that gap is not reproduced.
+fn escape_delimiter_runs(
+    text: Cow<'_, str>,
+    autolink_stretch: usize,
+    prev: Option<char>,
+    next: Option<char>,
+) -> Cow<'_, str> {
+    let bytes = text.as_bytes();
+    let mut out: Option<String> = None;
+    let mut emitted = 0;
+    let mut i = 0;
+    while i < bytes.len() {
+        let b = bytes[i];
+        if b != b'*' && b != b'_' {
+            i += 1;
+            continue;
+        }
+        // `*`, `_`, `\` are ASCII, so byte positions here are char boundaries
+        let run_start = i;
+        while i < bytes.len() && bytes[i] == b {
+            i += 1;
+        }
+        // A backslash escapes one character: the rest of the run is a run of its own
+        let run_start = run_start + usize::from(ends_with_unescaped_backslash(&text[..run_start]));
+        if run_start == i || run_start < autolink_stretch {
+            continue;
+        }
+        let preceding = text[..run_start].chars().next_back().or(prev);
+        let following = text[i..].chars().next().or(next);
+        if can_open_or_close(preceding, b as char, following) == Some(true) {
+            // Every character: escaping only the first leaves a shorter run that can still pair
+            let out = out.get_or_insert_with(|| String::with_capacity(text.len() + 2));
+            out.push_str(&text[emitted..run_start]);
+            for _ in run_start..i {
+                out.push('\\');
+                out.push(b as char);
+            }
+            emitted = i;
+        }
+    }
+    match out {
+        None => text,
+        Some(mut out) => {
+            out.push_str(&text[emitted..]);
+            Cow::Owned(out)
+        }
+    }
+}
+
+/// Whether the `*` / `_` run a word starts with is escaped where it stands (`escape_delimiter_runs`),
+/// so that the printed word starts with a backslash. `prev` / `next` as for the run's neighbors.
+pub fn leading_run_escaped(word: &str, prev: Option<char>, next: Option<char>) -> bool {
+    let Some(&marker) = word.as_bytes().first().filter(|b| matches!(b, b'*' | b'_')) else {
+        return false;
+    };
+    let run = word.bytes().take_while(|&b| b == marker).count();
+    let following = word[run..].chars().next().or(next);
+    can_open_or_close(prev, marker as char, following) == Some(true)
+}
+
+/// Whether a run of `indicator` could open or close emphasis here,
+/// by the parser's own rule (micromark's flanking, marker-adjacency relaxation included);
+/// `None` when a side is untouchable (an autolink, whose extent an escape would change).
+fn can_open_or_close(
+    preceding: Option<char>,
+    indicator: char,
+    following: Option<char>,
+) -> Option<bool> {
+    let (preceding, following) = (preceding?, following?);
+    let (open, close) =
+        attention::classify(indicator as u8, Some(preceding), Some(following), true);
+    Some(open || close)
+}
diff --git a/crates/oxc_formatter_markdown/src/print/inline.rs b/crates/oxc_formatter_markdown/src/print/inline.rs
new file mode 100644
index 0000000000..70a9292d7b
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/inline.rs
@@ -0,0 +1,754 @@
+//! Phrasing content: the node printers and the queries about a node's neighbors they need.
+//!
+//! A paragraph is ONE `fill` ([`Parts`]); `collect_inlines` pushes the nodes into it,
+//! `collect_phrasing` wraps that with the pre-passes and the pairing check.
+
+use std::borrow::Cow;
+
+use cow_utils::CowUtils;
+
+use oxc_markdown_parser::{
+    Span,
+    ast::{CodeSpan, Emphasis, HardBreakKind, Inline, LinkKind, Strong},
+    unicode,
+};
+
+use crate::{
+    context::{MarkdownFormatContext, Raw},
+    options::ProseWrap,
+    print::{Mark, pairing},
+};
+
+use super::{
+    HTML_WHITESPACE, MarkdownFormatter, backticks, escape, is_split_whitespace, join_pieces,
+    line_shape::{
+        is_line_shape_start, line_opens_block, line_or_prefix_opens_block, line_shape,
+        printed_line_opens_block, source_line_at,
+    },
+    link,
+    parts::{Atom, Parts, Sep},
+    text as words, with_depth,
+};
+
+/// Where the inline children hang; a few rules depend on the immediate parent.
+#[derive(Clone, Copy)]
+pub struct InlineParent {
+    /// The children are a paragraph's (its first / last text gets trimmed).
+    pub paragraph: bool,
+    /// The parent is an `Emphasis` / `Strong`: its marker character as printed (`*` / `_`),
+    /// the neighbor of the content's edge words.
+    pub delimiter: Option<u8>,
+    /// `Some(has_word_neighbor)` when the parent is a `Strong` (nested emphasis reads it).
+    pub strong_neighbor: Option<bool>,
+    /// The paragraph is the first block of a blockquote
+    /// (`[!NOTE]` on its first line is an alert marker).
+    pub first_in_container: bool,
+    /// The paragraph follows a task list checkbox on its line: its first line is not a line start.
+    pub after_checkbox: bool,
+    /// Nothing follows the parent node on its source line (its last child ends the line).
+    pub ends_line: bool,
+}
+
+impl Default for InlineParent {
+    fn default() -> Self {
+        Self {
+            paragraph: false,
+            delimiter: None,
+            strong_neighbor: None,
+            first_in_container: false,
+            after_checkbox: false,
+            ends_line: true,
+        }
+    }
+}
+
+/// Paragraph or heading content as one fill.
+pub fn write_inlines<'a>(
+    children: &'a [Inline<'a>],
+    parent: InlineParent,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) {
+    collect_phrasing(children, parent, f).write_fill(f);
+}
+
+/// One phrasing content (a paragraph, a heading, a table cell) collected.
+pub fn collect_phrasing<'a>(
+    children: &'a [Inline<'a>],
+    parent: InlineParent,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) -> Parts<'a> {
+    let raw = {
+        let mut opaque = f.context().opaque_spans().borrow_mut();
+        opaque.clear();
+        collect_opaque_spans(children, &mut opaque);
+        code_span_literal_runs(
+            children,
+            &opaque,
+            &mut f.context().code_span_literal_runs().borrow_mut(),
+            f,
+        );
+        parent.paragraph && wiki_link_risk(children, &opaque, f)
+    };
+    let collect = |initial: Raw, f: &mut MarkdownFormatter<'_, 'a>| {
+        let mut parts = Parts::new(f.allocator());
+        f.context().raw_text().set(initial);
+        collect_inlines(children, parent, &mut parts, f);
+        f.context().raw_text().set(Raw::No);
+        parts
+    };
+    let consistent = |parts: &Parts<'a>, f: &MarkdownFormatter<'_, 'a>| {
+        !parts.marks.iter().any(|m| matches!(m, Mark::Delimiter { .. }))
+            || pairing::consistent(parts.flat(f.allocator()), &parts.marks)
+    };
+    let initial = if raw { Raw::Text } else { Raw::No };
+    let mut parts = collect(initial, f);
+    // Normalized markers must pair as the source's did; otherwise the markers are printed as written,
+    // and if joined lines still pair differently, the text as written too
+    if !consistent(&parts, f) {
+        f.context().literal_markers().set(true);
+        parts = collect(initial, f);
+        if !consistent(&parts, f) {
+            parts = collect(Raw::Text, f);
+        }
+        f.context().literal_markers().set(false);
+    }
+    parts
+}
+
+/// For every code span, the backtick run lengths (bit `n - 1` for a run of `n`) that occur
+/// before it in the content as literal text
+/// (outside code spans, HTML, autolinks, math, liquid, whose backticks never delimit):
+/// a printed fence of such a length would pair with the run and move the span.
+fn code_span_literal_runs<'a>(
+    children: &'a [Inline<'a>],
+    opaque: &[(Span, bool)],
+    out: &mut Vec<(u32, u64)>,
+    f: &MarkdownFormatter<'_, 'a>,
+) {
+    out.clear();
+    let (Some(first), Some(last)) = (children.first(), children.last()) else { return };
+    let source = f.context().source_text();
+    if !source.bytes_contain(first.span().start, last.span().end, b'`') {
+        return;
+    }
+    let mut mask = 0;
+    let mut at = first.span().start;
+    for &(span, is_code) in opaque {
+        if span.start > at {
+            mask |= run_mask(source.slice_range(at, span.start).as_bytes(), b'`');
+        }
+        if is_code {
+            out.push((span.start, mask));
+        }
+        at = at.max(span.end);
+    }
+}
+
+/// Spans whose backticks are not code span delimiters, in source order;
+/// `true` marks code spans.
+fn collect_opaque_spans<'a>(children: &'a [Inline<'a>], out: &mut Vec<(Span, bool)>) {
+    for child in children {
+        match child {
+            Inline::CodeSpan(c) => out.push((c.span, true)),
+            Inline::HtmlInline(_)
+            | Inline::Autolink(_)
+            | Inline::AutolinkLiteral(_)
+            | Inline::MathSpan(_)
+            | Inline::Liquid(_)
+            | Inline::WikiLink(_) => out.push((child.span(), false)),
+            Inline::Emphasis(e) => collect_opaque_spans(&e.children, out),
+            Inline::Strong(s) => collect_opaque_spans(&s.children, out),
+            Inline::Strikethrough(s) => collect_opaque_spans(&s.children, out),
+            // Link text is inline content; a reference label or a title is not
+            Inline::Link(l) => {
+                collect_opaque_spans(&l.children, out);
+                collect_link_kind_spans(&l.kind, out);
+            }
+            Inline::Image(i) => {
+                collect_opaque_spans(&i.children, out);
+                collect_link_kind_spans(&i.kind, out);
+            }
+            _ => {}
+        }
+    }
+}
+
+fn collect_link_kind_spans(kind: &LinkKind<'_>, out: &mut Vec<(Span, bool)>) {
+    let pieces = match kind {
+        LinkKind::Reference { label, .. } => label,
+        LinkKind::Inline { title: Some(title), .. } => title,
+        LinkKind::Inline { title: None, .. } => return,
+    };
+    out.extend(pieces.iter().map(|piece| (piece.span, false)));
+}
+
+/// The emphasis marker as printed: `_` unless a word touches it (`1*2*3` is emphasis, `1_2_3` is not),
+/// the source marker around an autolink, on a raw line, and when a literal run of the target
+/// character before it could pair with it.
+fn emphasis_style<'a>(
+    e: &'a Emphasis<'a>,
+    children: &'a [Inline<'a>],
+    i: usize,
+    parent: InlineParent,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> &'static str {
+    let source = if e.marker == b'_' { "_" } else { "*" };
+    if markers_as_written(f)
+        || matches!(e.children.first(), Some(Inline::Autolink(_) | Inline::AutolinkLiteral(_)))
+    {
+        return source;
+    }
+    let word_neighbor = has_word_neighbor(children, i, f)
+        || parent.strong_neighbor == Some(true)
+        || f.context().emphasis_depth().get() > 0;
+    if word_neighbor { "*" } else { "_" }
+}
+
+/// `**`; `__` stays as written.
+fn strong_style<'a>(s: &'a Strong<'a>, f: &MarkdownFormatter<'_, 'a>) -> &'static str {
+    if s.marker == b'_' && markers_as_written(f) { "__" } else { "**" }
+}
+
+/// On a raw line, or when normalized markers would pair differently (`pairing`).
+fn markers_as_written(f: &MarkdownFormatter<'_, '_>) -> bool {
+    f.context().raw_text().get() == Raw::Line || f.context().literal_markers().get()
+}
+
+/// Under `proseWrap: preserve`, whether any soft break of this paragraph survives printing
+/// (one before a block-start-looking word is joined away; one next to a dialect shape line stays).
+pub fn keeps_a_line_break<'a>(children: &'a [Inline<'a>], f: &MarkdownFormatter<'_, 'a>) -> bool {
+    let last = children.len().wrapping_sub(1);
+    children.iter().enumerate().any(|(i, child)| {
+        matches!(child, Inline::SoftBreak(_))
+            && i != 0
+            && i != last
+            && (line_shape(children, i + 1, false, false, f)
+                || !words::prevents_break(
+                    true,
+                    next_word_of(children, i, None, f),
+                    ProseWrap::Preserve,
+                ))
+    })
+}
+
+/// Prettier's `riskyParagraphPositions`: a `[[` in text, followed by `]]` (text or a wiki link's).
+/// Wrapping such a paragraph could merge `[[foo\n[[wiki link]]` into one link,
+/// so its text is printed as written.
+/// Checked on the source, where a bracket pair split across nodes (`[` + `[link](u)`) still counts;
+/// a `[[` inside an opaque span (a wiki link's own, a code span, HTML) does not.
+fn wiki_link_risk<'a>(
+    children: &'a [Inline<'a>],
+    opaque: &[(Span, bool)],
+    f: &MarkdownFormatter<'_, 'a>,
+) -> bool {
+    let (Some(first), Some(last)) = (children.first(), children.last()) else { return false };
+    let start = first.span().start;
+    let raw = f.context().source_text().slice_range(start, last.span().end);
+    let Some(last_close) = raw.rfind("]]") else { return false };
+    raw[..last_close].match_indices("[[").any(|(at, _)| {
+        let abs = start + u32::try_from(at).unwrap_or(u32::MAX);
+        !opaque.iter().any(|(span, _)| span.contains(abs))
+    })
+}
+
+pub fn collect_inlines<'a>(
+    children: &'a [Inline<'a>],
+    parent: InlineParent,
+    parts: &mut Parts<'a>,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) {
+    let last = children.len().wrapping_sub(1);
+    // Raw text is switched per source line of a top-level paragraph:
+    // every line when wiki links are at risk, else the lines starting with a dialect shape.
+    // Nested content (emphasis, links) inherits the line's setting through the context.
+    let raw_paragraph = parent.paragraph && f.context().raw_text().get() != Raw::No;
+    let raw_for = |shape: bool| {
+        if shape {
+            Raw::Line
+        } else if raw_paragraph {
+            Raw::Text
+        } else {
+            Raw::No
+        }
+    };
+    let raw_line = |j: usize, f: &MarkdownFormatter<'_, 'a>| -> Raw {
+        raw_for(
+            parent.paragraph
+                && line_shape(children, j, j == 0, j == 0 && parent.first_in_container, f),
+        )
+    };
+    if parent.paragraph {
+        f.context().raw_text().set(raw_line(0, f));
+    }
+    // The soft break at `j` stays a line break: either side of it is raw
+    let break_kept = |j: usize, f: &MarkdownFormatter<'_, 'a>| -> bool {
+        f.context().raw_text().get() != Raw::No || raw_line(j + 1, f) != Raw::No
+    };
+    // Prettier's sentence is a run of texts joined by soft breaks; its CJ spacing style is one statistic.
+    let mut sentence_cj_spaces: Option<Option<bool>> = None;
+    // The previous sibling was a line break that stays in the output
+    let mut last_break_kept = false;
+    for (i, child) in children.iter().enumerate() {
+        if !matches!(child, Inline::Text(_) | Inline::SoftBreak(_)) {
+            sentence_cj_spaces = None;
+        }
+        let after_kept_break = last_break_kept;
+        if !matches!(child, Inline::SoftBreak(_) | Inline::HardBreak(_)) {
+            last_break_kept = false;
+        }
+        // After a kept line break, a line that would open a block at column 0 stays paragraph text
+        // behind four spaces (indented code cannot interrupt a paragraph)
+        if after_kept_break
+            && matches!(child, Inline::Text(_) | Inline::HtmlInline(_) | Inline::Liquid(_))
+            && printed_line_opens_block(children, i, &break_kept, f)
+        {
+            parts.push_str("    ");
+        }
+        match child {
+            Inline::Text(t) => {
+                let mut raw = f.context().slice(t.span);
+                // CommonMark keeps a paragraph's edge `\f`; HTML rendering drops it
+                if parent.paragraph {
+                    if i == 0 {
+                        raw = raw.trim_start_matches(HTML_WHITESPACE);
+                    }
+                    if i == last {
+                        raw = raw.trim_end_matches(HTML_WHITESPACE);
+                    }
+                }
+                if f.context().raw_text().get() != Raw::No {
+                    // A line ending with `\` would be a hard break
+                    let before_break = matches!(children.get(i + 1), Some(Inline::SoftBreak(_)));
+                    let mut lines = raw.split('\n').peekable();
+                    while let Some(line) = lines.next() {
+                        parts.push_str(line);
+                        let more = lines.peek().is_some();
+                        if (more || before_break) && escape::ends_with_unescaped_backslash(line) {
+                            parts.push_str("\\");
+                        }
+                        if more {
+                            parts.push_sep(Sep::HardLine);
+                        }
+                    }
+                    continue;
+                }
+                // Edge characters matter only inside emphasis (escaping)
+                let (edge_prev, edge_next) = if f.context().delimiter_depth().get() > 0 {
+                    (
+                        edge_char(children, i, parent.delimiter, true, f),
+                        edge_char(children, i, parent.delimiter, false, f),
+                    )
+                } else {
+                    (None, None)
+                };
+                let cj_spaces = *sentence_cj_spaces
+                    .get_or_insert_with(|| sentence_cj_spaces_at(children, i, f));
+                // A paragraph's first line that opens a block
+                // (the rest of a paragraph a definition was split from) is escaped: `\- x`, `1\. x`
+                if i == 0
+                    && parent.paragraph
+                    && !parent.after_checkbox
+                    && line_opens_block(source_line_at(children, t.span.start, f).1, false)
+                {
+                    let digits = raw.bytes().take_while(u8::is_ascii_digit).count();
+                    if digits > 0 && matches!(raw.as_bytes().get(digits), Some(b'.' | b')')) {
+                        parts.push_str(&raw[..digits]);
+                        raw = &raw[digits..];
+                    }
+                    parts.push_str("\\");
+                }
+                // Trailing punctuation after an autolink literal is where the link may still extend
+                let autolink_stretch = if matches!(
+                    children.get(i.wrapping_sub(1)),
+                    Some(Inline::AutolinkLiteral(_))
+                ) {
+                    raw.find(|c: char| unicode::is_whitespace(c) || c == '<').unwrap_or(raw.len())
+                } else {
+                    0
+                };
+                let cx = words::TextContext {
+                    autolink_stretch,
+                    first_of_delimiter: parent.delimiter.filter(|_| i == 0),
+                    last_of_delimiter: parent.delimiter.filter(|_| i == last),
+                    edge_prev,
+                    edge_next,
+                    after_soft_break: matches!(
+                        children.get(i.wrapping_sub(1)),
+                        Some(Inline::SoftBreak(_))
+                    ),
+                    before_soft_break: matches!(children.get(i + 1), Some(Inline::SoftBreak(_))),
+                    ends_line: ends_line(children, i, parent.ends_line),
+                    next_word: next_word_of(children, i, parent.delimiter, f),
+                    glued_last_word: glued_last_word(children, i, raw, f),
+                    cj_spaces,
+                    ..words::TextContext::default()
+                };
+                words::push_text(raw, cx, parts, f);
+            }
+            // A soft break at a paragraph edge (a task checkbox followed by a newline) is stripped
+            Inline::SoftBreak(_) if parent.paragraph && (i == 0 || i == last) => {}
+            Inline::SoftBreak(_) => {
+                let next_raw = raw_line(i + 1, f);
+                let keep = f.context().raw_text().get() != Raw::No || next_raw != Raw::No;
+                if parent.paragraph {
+                    f.context().raw_text().set(next_raw);
+                }
+                last_break_kept = keep;
+                if keep {
+                    // A separator, not content: the next line is measured on its own
+                    parts.push_sep(Sep::HardLine);
+                } else {
+                    let cj_spaces = *sentence_cj_spaces
+                        .get_or_insert_with(|| sentence_cj_spaces_at(children, i, f));
+                    let cx = words::TextContext {
+                        next_word: next_word_of(children, i, parent.delimiter, f),
+                        // Only the CJK rules look back (a trailing `\` was escaped by the text)
+                        prev_word: if cj_spaces.is_some() {
+                            prev_word_of(children, i, f)
+                        } else {
+                            None
+                        },
+                        cj_spaces,
+                        ..words::TextContext::default()
+                    };
+                    words::push_whitespace(true, &cx, parts, f);
+                }
+            }
+            Inline::HardBreak(b) => {
+                match b.kind {
+                    HardBreakKind::Spaces => {
+                        parts.push_str("  ");
+                        parts.push_atom(Atom::LiteralLine);
+                    }
+                    HardBreakKind::Backslash => {
+                        parts.push_str("\\");
+                        parts.push_atom(Atom::HardLine);
+                    }
+                }
+                if parent.paragraph {
+                    f.context().raw_text().set(raw_line(i + 1, f));
+                }
+                last_break_kept = true;
+            }
+            Inline::Emphasis(e) => {
+                let style = emphasis_style(e, children, i, parent, f);
+                let open = parts.len();
+                parts.push_str(style);
+                let inner = InlineParent {
+                    delimiter: Some(style.as_bytes()[0]),
+                    ends_line: ends_line(children, i, parent.ends_line),
+                    ..InlineParent::default()
+                };
+                with_depth(f, MarkdownFormatContext::emphasis_depth, |f| {
+                    with_depth(f, MarkdownFormatContext::delimiter_depth, |f| {
+                        collect_inlines(&e.children, inner, parts, f);
+                    });
+                });
+                mark_delimiter(open, parts, false);
+                parts.push_str(style);
+            }
+            Inline::Strong(s) => {
+                let style = strong_style(s, f);
+                let open = parts.len();
+                parts.push_str(style);
+                let inner = InlineParent {
+                    delimiter: Some(style.as_bytes()[0]),
+                    strong_neighbor: Some(has_word_neighbor(children, i, f)),
+                    ends_line: ends_line(children, i, parent.ends_line),
+                    ..InlineParent::default()
+                };
+                with_depth(f, MarkdownFormatContext::delimiter_depth, |f| {
+                    collect_inlines(&s.children, inner, parts, f);
+                });
+                mark_delimiter(open, parts, true);
+                parts.push_str(style);
+            }
+            Inline::Strikethrough(s) => {
+                let style = &"~~"[..usize::from(s.tildes)];
+                let open = parts.len();
+                parts.push_str(style);
+                let inner = InlineParent {
+                    ends_line: ends_line(children, i, parent.ends_line),
+                    ..InlineParent::default()
+                };
+                collect_inlines(&s.children, inner, parts, f);
+                mark_delimiter(open, parts, false);
+                parts.push_str(style);
+            }
+            Inline::Link(l) => link::collect_link(l, parts, f),
+            // Opaque to delimiter pairing (an image's alt text too: it is printed as written)
+            _ => {
+                let start = parts.len();
+                let raw = f.context().slice(child.span());
+                // A code span joins its lines: no newline in its printed text
+                let mut code_span_joined = false;
+                match child {
+                    Inline::CodeSpan(c) => {
+                        let printed = print_code_span(c, f);
+                        code_span_joined = !printed.contains('\n');
+                        parts.push_lines(printed, Atom::VerbatimLine);
+                    }
+                    Inline::Image(img) => link::collect_image(img, parts, f),
+                    Inline::HtmlInline(h) => {
+                        // Verbatim, continuation indentation included (mdast's `html` value is the source slice)
+                        parts.push_lines(join_pieces(&h.pieces, f), Atom::VerbatimLine);
+                    }
+                    Inline::WikiLink(w) => {
+                        let raw = f.context().slice(w.span);
+                        let inner = &raw[2..raw.len() - 2];
+                        parts.push_str("[[");
+                        if f.options().prose_wrap == ProseWrap::Preserve
+                            || !inner.contains(['\t', '\n'])
+                        {
+                            parts.push_str(inner);
+                        } else {
+                            parts.push_str(collapse_tabs_and_newlines(inner, f));
+                        }
+                        parts.push_str("]]");
+                    }
+                    Inline::Liquid(l) => {
+                        parts.push_lines(join_pieces(&l.pieces, f), Atom::VerbatimLine);
+                    }
+                    // Printed as written: remark-math trims math spans, but the match may be accidental
+                    Inline::MathSpan(m) => {
+                        parts.push_lines(join_pieces(&m.pieces, f), Atom::VerbatimLine);
+                    }
+                    // Printed as written; single-line by construction.
+                    _ => parts.push_str(raw),
+                }
+                parts.mark(Mark::Opaque { start, end: parts.len() });
+                // A newline inside the node starts a source line with the node's tail; what follows
+                // on that line may be cut by wrapping (`$$\n$$ text`: `$$` alone opens math),
+                // so such a line stays as written
+                if parent.paragraph
+                    && !code_span_joined
+                    && let Some(newline) = raw.rfind('\n')
+                {
+                    let line_start = child.span().start + u32::try_from(newline).unwrap_or(0) + 1;
+                    let (base, line) = source_line_at(children, line_start, f);
+                    let risky = is_line_shape_start(line)
+                        || line_or_prefix_opens_block(line, base, true, f);
+                    f.context().raw_text().set(raw_for(risky));
+                }
+            }
+        }
+    }
+}
+
+/// Records a delimiter node whose opening marker was pushed at `open` and whose closing marker
+/// is about to be pushed.
+fn mark_delimiter(open: u32, parts: &mut Parts<'_>, strong: bool) {
+    parts.mark(Mark::Delimiter { open, close: parts.len(), strong });
+}
+
+/// Bit `n - 1` set: a run of exactly `n` `ch`s occurs in `bytes` (runs past 64 count as 64).
+fn run_mask(bytes: &[u8], ch: u8) -> u64 {
+    let mut present: u64 = 0;
+    let mut run = 0usize;
+    for &b in bytes.iter().chain(std::iter::once(&0)) {
+        if b == ch {
+            run += 1;
+        } else if run > 0 {
+            present |= 1u64 << (run.min(64) - 1);
+            run = 0;
+        }
+    }
+    present
+}
+
+/// The smallest run length of `ch` absent from `text`.
+fn min_absent_run(text: &str, ch: u8) -> usize {
+    run_mask(text.as_bytes(), ch).trailing_ones() as usize + 1
+}
+
+/// Runs of tabs / newlines become one space (wiki link contents under wrapping).
+fn collapse_tabs_and_newlines<'a>(s: &str, f: &MarkdownFormatter<'_, 'a>) -> &'a str {
+    let mut out = oxc_allocator::StringBuilder::with_capacity_in(s.len(), f.allocator());
+    let mut in_run = false;
+    for c in s.chars() {
+        if c == '\t' || c == '\n' {
+            if !in_run {
+                out.push(' ');
+                in_run = true;
+            }
+        } else {
+            out.push(c);
+            in_run = false;
+        }
+    }
+    out.into_str()
+}
+
+/// The first word the next sibling starts, for the whitespace that ends this one
+/// (any node wrapped to a line start may open a block: `<!--`, `<div>`, `$$`, `{% t %}`, `[[toc]]`).
+/// `delimiter`: the enclosing emphasis marker, the edge character past the last sibling.
+fn next_word_of<'a>(
+    children: &'a [Inline<'a>],
+    i: usize,
+    delimiter: Option<u8>,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> Option<words::NextWord<'a>> {
+    let next = children.get(i + 1)?;
+    if matches!(next, Inline::SoftBreak(_) | Inline::HardBreak(_)) {
+        return None;
+    }
+    // The word runs across nodes (`[^1]:` is a footnote reference and a text)
+    let (word, alone_on_line) = first_word_at(children, next.span().start, f)?;
+    // A text's leading run after a soft break is escaped inside emphasis
+    // (as `push_text` decides: a space before it, and after it the text's next character or the node edge)
+    let escaped = matches!(next, Inline::Text(_))
+        && f.context().delimiter_depth().get() > 0
+        && !f.context().literal_markers().get()
+        && escape::leading_run_escaped(
+            word,
+            Some(' '),
+            edge_char(children, i + 1, delimiter, false, f),
+        );
+    Some(words::NextWord { word, alone_on_line, escaped })
+}
+
+/// The first word of the source line starting at `start`, and whether it is the line's only one.
+fn first_word_at<'a>(
+    children: &[Inline<'_>],
+    start: u32,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> Option<(&'a str, bool)> {
+    let (_, line) = source_line_at(children, start, f);
+    let mut it = line.split(is_split_whitespace).filter(|w| !w.is_empty());
+    let word = it.next()?;
+    Some((word, it.next().is_none()))
+}
+
+/// Nothing follows node `i` on its source line (a node glued after it would be part of the line);
+/// past the last sibling, whether the parent ends its line.
+fn ends_line(children: &[Inline<'_>], i: usize, parent_ends_line: bool) -> bool {
+    match children.get(i + 1) {
+        None => parent_ends_line,
+        Some(Inline::SoftBreak(_) | Inline::HardBreak(_)) => true,
+        Some(_) => false,
+    }
+}
+
+/// The character right before (`before`) or after the text at `i`, as it will be printed:
+/// a space for a line break, the neighbor node's edge character, the enclosing emphasis marker;
+/// `None` at the edge of a paragraph.
+fn edge_char<'a>(
+    children: &'a [Inline<'a>],
+    i: usize,
+    delimiter: Option<u8>,
+    before: bool,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> Option<char> {
+    let neighbor =
+        if before { i.checked_sub(1).map(|j| &children[j]) } else { children.get(i + 1) };
+    match neighbor {
+        Some(Inline::SoftBreak(_) | Inline::HardBreak(_)) => Some(' '),
+        // An autolink's extent depends on what follows it: escaping there changes the URL
+        Some(Inline::Autolink(_) | Inline::AutolinkLiteral(_)) => None,
+        Some(node) => {
+            let raw = f.context().slice(node.span());
+            if before { raw.chars().next_back() } else { raw.chars().next() }
+        }
+        // A paragraph edge is a boundary, whitespace to the flanking rules
+        None => delimiter.map_or(Some(' '), |m| Some(char::from(m))),
+    }
+}
+
+/// The last word of text `i` (its printed `raw`) extended by the nodes glued after it
+/// on its source line (a backslash hard break's `\` included), and whether it is the line's last word.
+fn glued_last_word<'a>(
+    children: &'a [Inline<'a>],
+    i: usize,
+    raw: &str,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> Option<(&'a str, bool)> {
+    // Nothing glues after whitespace, a line end, or a two-space hard break
+    match children.get(i + 1) {
+        None | Some(Inline::SoftBreak(_)) => return None,
+        Some(Inline::HardBreak(b)) if b.kind == HardBreakKind::Spaces => return None,
+        _ if raw.ends_with(is_split_whitespace) => return None,
+        _ => {}
+    }
+    let last = raw.rsplit(is_split_whitespace).next()?;
+    let start = children[i].span().end - u32::try_from(last.len()).unwrap_or(0);
+    first_word_at(children, start, f).filter(|(word, _)| word.len() != last.len())
+}
+
+/// The last word of the text before node `i`.
+fn prev_word_of<'a>(
+    children: &'a [Inline<'a>],
+    i: usize,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> Option<&'a str> {
+    let Some(Inline::Text(t)) = children.get(i.checked_sub(1)?) else { return None };
+    f.context().slice(t.span).rsplit(is_split_whitespace).find(|w| !w.is_empty())
+}
+
+/// `usesCJSpaces` of the sentence (run of texts and soft breaks) containing node `i`;
+/// `None` without CJK text, which is the common case and skips the scan and the CJK rules.
+fn sentence_cj_spaces_at<'a>(
+    children: &'a [Inline<'a>],
+    i: usize,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> Option<bool> {
+    let in_sentence = |c: &Inline<'a>| matches!(c, Inline::Text(_) | Inline::SoftBreak(_));
+    let start = (0..i).rev().take_while(|&j| in_sentence(&children[j])).last().unwrap_or(i);
+    let end = (i..children.len()).take_while(|&j| in_sentence(&children[j])).last().unwrap_or(i);
+    let texts = children[start..=end].iter().filter_map(|c| match c {
+        Inline::Text(t) => Some(t),
+        _ => None,
+    });
+    if !texts.clone().any(|t| t.contains_cjk) {
+        return None;
+    }
+    Some(words::uses_cj_spaces(texts.map(|t| f.context().slice(t.span))))
+}
+
+/// A word character directly before or after node `i`.
+fn has_word_neighbor<'a>(
+    children: &'a [Inline<'a>],
+    i: usize,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> bool {
+    let is_word_char = |c: char| !unicode::is_whitespace(c) && !unicode::is_punctuation(c);
+    let before = i > 0
+        && matches!(&children[i - 1], Inline::Text(t)
+            if f.context().slice(t.span).chars().next_back().is_some_and(is_word_char));
+    let after = matches!(children.get(i + 1), Some(Inline::Text(t))
+        if f.context().slice(t.span).chars().next().is_some_and(is_word_char));
+    before || after
+}
+
+/// Backtick fence of the shortest length the content permits that no literal backtick run of the
+/// paragraph shares (a fence equal to a stray run would pair with it and move the span:
+/// Prettier's content-only rule, prettier/prettier#6035).
+/// A space pads content that starts / ends with a backtick or is surrounded by spaces (CommonMark strips one).
+/// Inside a table cell a `|` is `\|` in the source and stays so
+/// (the raw slice already carries the escape Prettier re-adds to its decoded value).
+fn print_code_span<'a>(code: &'a CodeSpan<'a>, f: &MarkdownFormatter<'_, 'a>) -> &'a str {
+    let joined = join_pieces(&code.pieces, f);
+    // Raw text keeps its line breaks: joining `[[\`a\nb\`]]` onto one line would form a wiki link
+    let value: Cow<'_, str> = if f.options().prose_wrap == ProseWrap::Preserve
+        || f.context().raw_text().get() != Raw::No
+    {
+        Cow::Borrowed(joined)
+    } else {
+        joined.cow_replace('\n', " ")
+    };
+    let runs = f.context().code_span_literal_runs().borrow();
+    let literal_runs =
+        runs.binary_search_by_key(&code.span.start, |&(start, _)| start).map_or(0, |i| runs[i].1);
+    let mut len = min_absent_run(&value, b'`');
+    while len <= 64 && literal_runs & (1u64 << (len - 1)) != 0 {
+        len += 1;
+    }
+    let fence = backticks(len);
+    let is_space_or_newline = |c: char| c == ' ' || c == '\n';
+    let padding = value.starts_with('`')
+        || value.ends_with('`')
+        || (value.starts_with(is_space_or_newline)
+            && value.ends_with(is_space_or_newline)
+            && value.chars().any(|c| !is_space_or_newline(c)));
+    let padding = if padding { " " } else { "" };
+    f.allocator().alloc_concat_strs_array([&fence, padding, &value, padding, &fence])
+}
diff --git a/crates/oxc_formatter_markdown/src/print/line_shape.rs b/crates/oxc_formatter_markdown/src/print/line_shape.rs
new file mode 100644
index 0000000000..b124f97a25
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/line_shape.rs
@@ -0,0 +1,201 @@
+//! What a printed line would open.
+//!
+//! Wrapping moves words to line starts and joins source lines;
+//! a line that then reads as a block start would leave the paragraph.
+//! These predicates ask the parser (`lexical::line_start`) about the line the printer is about to produce.
+//! The dialect line shapes (AGENTS.md "Dialects") live here too.
+
+use cow_utils::CowUtils;
+
+use oxc_markdown_parser::{Constructs, ast::Inline, lexical};
+
+use crate::{context::Raw, options::ProseWrap};
+
+use super::{HTML_WHITESPACE, MarkdownFormatter, is_split_whitespace};
+
+/// HTML whitespace: `\t\n\f\r` and space.
+/// Dialect line shapes (see AGENTS.md "Dialects"):
+/// a source line starting with one of these keeps both its line boundaries and is never re-wrapped,
+/// whatever `proseWrap` says.
+/// `alert`: the line is the first of a blockquote's first paragraph (`[!NOTE]`).
+pub fn line_shape<'a>(
+    children: &'a [Inline<'a>],
+    j: usize,
+    first_line: bool,
+    alert: bool,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> bool {
+    let Some(inline) = children.get(j) else { return false };
+    if matches!(inline, Inline::SoftBreak(_) | Inline::HardBreak(_)) {
+        return false;
+    }
+    // The whole source line from this node on (a liquid tag, a tag, text: whatever starts it)
+    let (base, raw) = source_line_at(children, inline.span().start, f);
+    // The shapes, an alert, and a line that is not a block only because of what follows on it
+    // (`[label]: dest text`, ``` ```a `b` ```, `$$x $y$`, `</span> text` on a first line):
+    // a wrap inside it would leave the block behind.
+    // (A first line that opens a block as a whole is escaped instead, or printed after its definition;
+    // a continuation line's start is guarded where it stays, after a kept break.)
+    is_line_shape_start(raw)
+        || (alert && raw.starts_with("[!"))
+        || is_unfinished_block_shape(raw, matches!(inline, Inline::Text(_)), first_line)
+        || (first_line
+            && !line_opens_block(raw, false)
+            && line_prefix_opens_block(raw, base, false, f))
+}
+
+/// The source line starting at offset `start` (nodes after it on the line included),
+/// up to the content's end, without the leading whitespace the printer drops;
+/// with the offset it then starts at.
+pub fn source_line_at<'a>(
+    children: &[Inline<'_>],
+    start: u32,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> (u32, &'a str) {
+    let end = children.last().map_or(start, |last| last.span().end);
+    let raw = f.context().source_text().slice_range(start, end.max(start));
+    let line = raw.trim_start_matches(HTML_WHITESPACE);
+    let base = start + u32::try_from(raw.len() - line.len()).unwrap_or(0);
+    (base, line.split('\n').next().unwrap_or(line))
+}
+
+/// Whether the line, or any prefix wrapping may cut it to, opens a block.
+pub fn line_or_prefix_opens_block(
+    line: &str,
+    base: u32,
+    in_paragraph: bool,
+    f: &MarkdownFormatter<'_, '_>,
+) -> bool {
+    line_opens_block(line, in_paragraph) || line_prefix_opens_block(line, base, in_paragraph, f)
+}
+
+/// Whether a proper prefix of the line, cut at a whitespace outside opaque nodes
+/// (a code span is one atom), opens a block. `base`: the line's source offset.
+pub fn line_prefix_opens_block(
+    line: &str,
+    base: u32,
+    in_paragraph: bool,
+    f: &MarkdownFormatter<'_, '_>,
+) -> bool {
+    if !line.as_bytes().first().is_some_and(|&b| may_open_block(b)) {
+        return false;
+    }
+    let opaque = f.context().opaque_spans().borrow();
+    line.match_indices(is_split_whitespace).any(|(at, _)| {
+        let offset = base + u32::try_from(at).unwrap_or(u32::MAX);
+        !opaque.iter().any(|(span, _)| span.contains(offset))
+            && line_opens_block(&line[..at], in_paragraph)
+    })
+}
+
+/// A paragraph whose first line, printed at a block start,
+/// opens a block that no escape can prevent (a tag: `<Badge />`, `</span>`).
+/// Such a paragraph is the rest of one a definition was split from;
+/// printed right after the definition, as in the source, its line stays a continuation.
+pub fn first_line_opens_block(children: &[Inline<'_>], f: &MarkdownFormatter<'_, '_>) -> bool {
+    match children.first() {
+        None | Some(Inline::Text(_)) => false,
+        Some(first) => line_opens_block(source_line_at(children, first.span().start, f).1, false),
+    }
+}
+
+/// After a kept line break before node `i`:
+/// whether a line the printer may produce from there opens a block.
+/// Under `preserve` (and on a raw line) that is the source line.
+/// Otherwise the source lines up to the next kept break are joined,
+/// and the printed line is that text (`never`) or any prefix of it ending at a word boundary (`always`);
+/// each is a candidate, which keeps the decision the same on every pass
+/// (`| - | - | a` may wrap to a delimiter row `| - | - |`, `:-` may join to `:- ]`).
+pub fn printed_line_opens_block<'a>(
+    children: &'a [Inline<'a>],
+    i: usize,
+    break_kept: &dyn Fn(usize, &MarkdownFormatter<'_, 'a>) -> bool,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> bool {
+    // The source line runs to the line end
+    // (through a backslash hard break: `---\` is no thematic break)
+    let (_, line) = source_line_at(children, children[i].span().start, f);
+    if !line.as_bytes().first().is_some_and(|&b| may_open_block(b)) {
+        return false;
+    }
+    let prose_wrap = f.options().prose_wrap;
+    if prose_wrap == ProseWrap::Preserve || f.context().raw_text().get() != Raw::No {
+        return line_opens_block(line, true);
+    }
+    let start = children[i].span().start;
+    let end = children
+        .iter()
+        .enumerate()
+        .skip(i + 1)
+        .find_map(|(j, c)| match c {
+            Inline::HardBreak(_) => Some(c.span().start),
+            Inline::SoftBreak(_) if break_kept(j, f) => Some(c.span().start),
+            _ => None,
+        })
+        .unwrap_or_else(|| children[children.len() - 1].span().end);
+    let segment = f.context().source_text().slice_range(start, end);
+    let trimmed = segment.trim_start_matches(HTML_WHITESPACE);
+    let joined = trimmed.cow_replace('\n', " ");
+    if prose_wrap == ProseWrap::Always {
+        let base = start + u32::try_from(segment.len() - trimmed.len()).unwrap_or(0);
+        line_or_prefix_opens_block(&joined, base, true, f)
+    } else {
+        line_opens_block(&joined, true)
+    }
+}
+
+/// The line, printed at column 0, would open a block:
+/// as a paragraph continuation (`in_paragraph`, where setext underlines and table delimiter rows also count)
+/// or as a paragraph's first line.
+/// A bare `:::` run only closes, and a `|` row is inert without a table.
+pub fn line_opens_block(line: &str, in_paragraph: bool) -> bool {
+    match lexical::line_start(&Constructs::markdown(), line, in_paragraph) {
+        None | Some(lexical::LineStart::TableRow | lexical::LineStart::DirectiveCloser) => false,
+        Some(_) => true,
+    }
+}
+
+/// A line that is not a block only because of what follows on it:
+/// a fence or math opener whose info has a backtick or a `$` (they interrupt a paragraph, so any line counts),
+/// a liquid tag, and on a paragraph's first line a definition (`[label]: dest text`; one cannot interrupt).
+/// `is_text`: the line starts with text (a code span or math span is one atom and never wraps inside).
+fn is_unfinished_block_shape(raw: &str, is_text: bool, first_line: bool) -> bool {
+    (is_text
+        && ((first_line
+            && raw.starts_with('[')
+            && raw.find(']').is_some_and(|i| raw[i + 1..].starts_with(':')))
+            || raw.starts_with("```")
+            || raw.starts_with("~~~")
+            || raw.starts_with("$$")))
+        || raw.starts_with("{%")
+        || raw.starts_with("{{")
+}
+
+/// Every block start (and line shape) begins with one of these bytes.
+pub fn may_open_block(first: u8) -> bool {
+    matches!(
+        first,
+        b'>' | b'=' | b'-' | b'*' | b'_' | b'+' | b'0'
+            ..=b'9' | b'#' | b'`' | b'~' | b'<' | b'$' | b'{' | b':' | b'[' | b'|'
+    )
+}
+
+/// Dialect line shapes (see AGENTS.md "Dialects") that a line may start with:
+/// a `:::` run that is not a directive opener (a bare closer, `:::)`), a VitePress `<<<` snippet import,
+/// a component tag (`<Badge />`, `<my-element>`: uppercase or hyphenated names, which are not HTML).
+pub fn is_line_shape_start(line: &str) -> bool {
+    (line.starts_with(":::")
+        && lexical::line_start(&Constructs::markdown(), line, false)
+            != Some(lexical::LineStart::DirectiveOpener))
+        || line.starts_with("<<<")
+        || is_component_tag(line)
+}
+
+fn is_component_tag(raw: &str) -> bool {
+    let Some(rest) = raw.strip_prefix('<') else { return false };
+    let rest = rest.strip_prefix('/').unwrap_or(rest);
+    let name_len = rest.bytes().take_while(|b| b.is_ascii_alphanumeric() || *b == b'-').count();
+    let name = &rest[..name_len];
+    name.starts_with(|c: char| c.is_ascii_uppercase())
+        || (name.contains('-') && name.starts_with(|c: char| c.is_ascii_alphabetic()))
+}
diff --git a/crates/oxc_formatter_markdown/src/print/link.rs b/crates/oxc_formatter_markdown/src/print/link.rs
new file mode 100644
index 0000000000..96a9c44c5b
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/link.rs
@@ -0,0 +1,277 @@
+//! Links, images and definitions:
+//! destinations and titles are re-derived from their cooked values,
+//! reference forms other than `[text][label]` are re-emitted from the source.
+
+use oxc_allocator::StringBuilder;
+use oxc_formatter_core::{
+    Buffer,
+    builders::{group, indent, soft_line_break_or_space, text, token},
+    write,
+};
+use oxc_markdown_parser::{
+    Constructs, Segment,
+    ast::{Definition, Image, Inline, Link, LinkKind, ReferenceKind},
+    decode, lexical,
+};
+
+use crate::{context::MarkdownFormatContext, options::ProseWrap, print::Mark};
+
+use super::{
+    MarkdownFormatter, format_with,
+    inline::{InlineParent, collect_inlines},
+    join_pieces,
+    parts::{Atom, Parts},
+    text as words, with_depth,
+};
+
+pub fn collect_link<'a>(
+    link: &'a Link<'a>,
+    parts: &mut Parts<'a>,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) {
+    parts.push_str("[");
+    match &link.kind {
+        LinkKind::Inline { .. } | LinkKind::Reference { kind: ReferenceKind::Full, .. } => {
+            // Link text never wraps; its delimiter runs pair on their own (bracket level)
+            let text_start = parts.len();
+            with_depth(f, MarkdownFormatContext::no_wrap_depth, |f| {
+                collect_inlines(&link.children, InlineParent::default(), parts, f);
+            });
+            let text_end = parts.len();
+            push_target(&link.kind, parts, f);
+            parts.mark(Mark::Group { start: text_start, end: text_end });
+            parts.mark(Mark::Opaque { start: text_end, end: parts.len() });
+        }
+        LinkKind::Reference { kind, .. } => {
+            // Kept as written, re-split into words for wrapping
+            collect_raw_children(&link.children, parts, f);
+            parts.push_str("]");
+            if *kind == ReferenceKind::Collapsed {
+                parts.push_str("[]");
+            }
+        }
+    }
+}
+
+pub fn collect_image<'a>(
+    image: &'a Image<'a>,
+    parts: &mut Parts<'a>,
+    f: &MarkdownFormatter<'_, 'a>,
+) {
+    match &image.kind {
+        LinkKind::Inline { .. } | LinkKind::Reference { kind: ReferenceKind::Full, .. } => {
+            parts.push_str("![");
+            parts.push_lines(join_pieces(&image.alt, f), Atom::VerbatimLine);
+            push_target(&image.kind, parts, f);
+        }
+        LinkKind::Reference { kind, label } => {
+            parts.push_str("!");
+            parts.push_str(print_label(label, f));
+            if *kind == ReferenceKind::Collapsed {
+                parts.push_str("[]");
+            }
+        }
+    }
+}
+
+/// What follows the text of an inline (`](url "title")`) or full-reference (`][label]`) link.
+fn push_target<'a>(kind: &LinkKind<'a>, parts: &mut Parts<'a>, f: &MarkdownFormatter<'_, 'a>) {
+    match kind {
+        LinkKind::Inline { destination, title } => {
+            let source = f.context().source_text().as_str();
+            let url = decode::destination(source, destination);
+            parts.push_str("](");
+            parts.push_str(if url.is_empty() { "<>" } else { print_url(&url, false, f) });
+            if let Some(title) = title {
+                let cooked = decode::title(source, title);
+                if !cooked.is_empty() {
+                    parts.push_str(" ");
+                    parts.push_lines(print_title(&cooked, f), Atom::VerbatimLine);
+                }
+            }
+            parts.push_str(")");
+        }
+        LinkKind::Reference { label, .. } => {
+            parts.push_str("]");
+            parts.push_str(print_label(label, f));
+        }
+    }
+}
+
+/// Each child as its source text, split into words for wrapping only.
+fn collect_raw_children<'a>(
+    children: &'a [Inline<'a>],
+    parts: &mut Parts<'a>,
+    f: &MarkdownFormatter<'_, 'a>,
+) {
+    let cx = words::TextContext { is_link: true, ..words::TextContext::default() };
+    for child in children {
+        match child {
+            Inline::SoftBreak(_) => {
+                words::push_whitespace(true, &cx, parts, f);
+            }
+            _ => words::push_text(f.context().slice(child.span()), cx, parts, f),
+        }
+    }
+}
+
+/// `[label]: url "title"`, breaking after the colon under `proseWrap: always`.
+pub fn write_definition<'a>(definition: &'a Definition<'a>, f: &mut MarkdownFormatter<'_, 'a>) {
+    let source = f.context().source_text().as_str();
+    let label = print_label(&definition.label, f);
+    let url = decode::destination(source, &definition.destination);
+    let url: &'a str = if url.is_empty() { "<>" } else { print_url(&url, true, f) };
+    // An empty title (`""`) is dropped
+    let title: Option<&'a str> = definition
+        .title
+        .as_ref()
+        .map(|title| decode::title(source, title))
+        .filter(|cooked| !cooked.is_empty())
+        .map(|cooked| print_title(&cooked, f));
+    // A destination wrapped to its own line must not open a block there (`:::x`, `<div>`)
+    let always = f.options().prose_wrap == ProseWrap::Always
+        && lexical::line_start(&Constructs::markdown(), url, false).is_none();
+    let line_or_space = format_with(move |f| {
+        if always {
+            write!(f, soft_line_break_or_space());
+        } else {
+            write!(f, token(" "));
+        }
+    });
+    write!(
+        f,
+        group(&format_with(|f| {
+            write!(f, [text(label), token(":")]);
+            write!(
+                f,
+                indent(&format_with(|f| {
+                    write!(f, [line_or_space, text(url)]);
+                    if let Some(title) = title {
+                        // A multi-line title prints as is; its newlines do not break the group
+                        write!(f, [line_or_space, text(title).without_expand_parent()]);
+                    }
+                }))
+            );
+        }))
+    );
+}
+
+/// `[label]`: the cooked label with whitespace collapsed and `\`,
+/// `[`, `]` escaped (escaping the raw text would double its escapes on every run).
+fn print_label<'a>(pieces: &[Segment], f: &MarkdownFormatter<'_, 'a>) -> &'a str {
+    let raw = join_pieces(pieces, f);
+    let joined = decode::decode(raw, true);
+    // Decoding frees at least the byte each re-added escape costs, so the raw length bounds the output
+    let mut out = StringBuilder::with_capacity_in(raw.len() + 2, f.allocator());
+    out.push('[');
+    let mut in_ws = false;
+    for c in joined.chars() {
+        if super::is_split_whitespace(c) {
+            if !in_ws {
+                out.push(' ');
+                in_ws = true;
+            }
+            continue;
+        }
+        in_ws = false;
+        if matches!(c, '\\' | '[' | ']') {
+            out.push('\\');
+        }
+        out.push(c);
+    }
+    out.push(']');
+    out.into_str()
+}
+
+/// The destination as Prettier `main` prints it (prettier/prettier#19482, #19849, #19891):
+///
+/// - `\` followed by ASCII punctuation, or last, is doubled (it would start an escape)
+/// - `&` that would start a character reference becomes `\&`
+/// - the whole thing is wrapped in `<>`, inner `<` / `>` escaped, when it holds whitespace,
+///   a control character, a leading `<`, or parentheses;
+///   definitions tolerate balanced parentheses (CommonMark: nested up to three deep)
+fn print_url<'a>(
+    url: &str,
+    unwrap_balanced_parens: bool,
+    f: &MarkdownFormatter<'_, 'a>,
+) -> &'a str {
+    let bytes = url.as_bytes();
+    let needs_brackets = bytes.iter().any(|&b| b.is_ascii_control() || b == b' ')
+        || url.starts_with('<')
+        || if unwrap_balanced_parens {
+            !has_balanced_parens(url)
+        } else {
+            url.contains(['(', ')'])
+        };
+    let mut out = StringBuilder::with_capacity_in(url.len() + 2, f.allocator());
+    if needs_brackets {
+        out.push('<');
+    }
+    for (i, c) in url.char_indices() {
+        match c {
+            '\\' if bytes.get(i + 1).is_none_or(u8::is_ascii_punctuation) => out.push_str("\\\\"),
+            '&' if decode::entity(url, i).is_some() => out.push_str("\\&"),
+            '<' | '>' if needs_brackets => {
+                out.push('\\');
+                out.push(c);
+            }
+            _ => out.push(c),
+        }
+    }
+    if needs_brackets {
+        out.push('>');
+    }
+    out.into_str()
+}
+
+/// Balanced parentheses nested at most three deep.
+fn has_balanced_parens(url: &str) -> bool {
+    let mut depth = 0i32;
+    for c in url.chars() {
+        match c {
+            '(' => {
+                depth += 1;
+                if depth > 3 {
+                    return false;
+                }
+            }
+            ')' => {
+                depth -= 1;
+                if depth < 0 {
+                    return false;
+                }
+            }
+            _ => {}
+        }
+    }
+    depth == 0
+}
+
+/// The title in the preferred quote (see `MarkdownFormatOptions::preferred_quote`),
+/// or `(...)` when both quotes appear and no parenthesis does (prettier/prettier#19890).
+/// Backslashes, the chosen quote and character-reference `&`s are escaped.
+fn print_title<'a>(title: &str, f: &MarkdownFormatter<'_, 'a>) -> &'a str {
+    let parenthesized = title.contains('"') && title.contains('\'') && !title.contains(['(', ')']);
+    let (open, close, quote) = if parenthesized {
+        ('(', ')', None)
+    } else {
+        let quote = f.options().preferred_quote(title) as char;
+        (quote, quote, Some(quote))
+    };
+
+    let mut out = StringBuilder::with_capacity_in(title.len() + 2, f.allocator());
+    out.push(open);
+    for (i, c) in title.char_indices() {
+        match c {
+            '\\' => out.push_str("\\\\"),
+            '&' if decode::entity(title, i).is_some() => out.push_str("\\&"),
+            _ if Some(c) == quote => {
+                out.push('\\');
+                out.push(c);
+            }
+            _ => out.push(c),
+        }
+    }
+    out.push(close);
+    out.into_str()
+}
diff --git a/crates/oxc_formatter_markdown/src/print/list.rs b/crates/oxc_formatter_markdown/src/print/list.rs
new file mode 100644
index 0000000000..b94812dc6a
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/list.rs
@@ -0,0 +1,311 @@
+//! Markers normalize: bullets alternate `-` / `*`
+//! and ordered delimiters `.` / `)` between adjacent sibling lists (so two lists stay two lists);
+//! numbers renumber from the first item's
+//! (all the same when the second item repeats `1`, "git-diff friendly").
+
+use oxc_formatter_core::{
+    Buffer,
+    builders::{align, mark_as_root, text, token},
+    write,
+};
+use oxc_markdown_parser::{
+    ast::{Block, CodeBlockKind, List, ListItem, ListMarker, TaskCheckbox},
+    lexical,
+};
+
+use crate::context::ListFrame;
+
+use super::{MarkdownFormatter, block, column_of, format_with, write_gap};
+
+fn is_ordered(list: &List<'_>) -> bool {
+    matches!(list.marker, ListMarker::Ordered { .. })
+}
+
+fn is_indented_code(block: &Block<'_>) -> bool {
+    matches!(block, Block::CodeBlock(code) if matches!(code.kind, CodeBlockKind::Indented))
+}
+
+/// The maximum number CommonMark parses as a list item number.
+const MAXIMUM_ORDERED_LIST_MARKER: u64 = 999_999_999;
+
+pub fn write_list<'a>(
+    list: &'a List<'a>,
+    siblings: &'a [Block<'a>],
+    index: usize,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) {
+    let alternate_marker = uses_alternate_marker(list, siblings, index, f);
+    let git_diff_friendly = has_git_diff_friendly_ordered_list(list, f);
+    let next = siblings.get(index + 1);
+    let aligned = is_aligned(list, next, f);
+    let min_indent = required_indent(next, f);
+    let indent_width = usize::from(f.options().indent_width.value());
+    let ordered = is_ordered(list);
+    let start = list.children.first().map_or(1, |item| marker_number(item, f));
+
+    f.context().lists().borrow_mut().push(ListFrame { alternate_marker, aligned });
+
+    let mut previous_loose = false;
+    for (i, item) in list.children.iter().enumerate() {
+        if i > 0 {
+            write_gap(previous_loose, f);
+        }
+        let loose = is_loose_item(item, list.children.get(i + 1), f);
+        previous_loose = loose;
+        let checkbox = match item.checkbox {
+            Some(TaskCheckbox { checked: true, .. }) => "[x] ",
+            Some(TaskCheckbox { checked: false, .. }) => "[ ] ",
+            None => "",
+        };
+
+        let mut prefix = String::new();
+        if ordered {
+            let number = if i == 0 {
+                start
+            } else if git_diff_friendly {
+                1
+            } else {
+                (start + i as u64).min(MAXIMUM_ORDERED_LIST_MARKER)
+            };
+            prefix.push_str(&number.to_string());
+            prefix.push_str(if alternate_marker { ") " } else { ". " });
+            if aligned {
+                align_list_prefix(&mut prefix, indent_width);
+            }
+        } else {
+            prefix.push_str(if alternate_marker { "* " } else { "- " });
+        }
+        pad_to_min_indent(&mut prefix, min_indent);
+
+        // An empty item is just its marker (the printer never trims trailing whitespace).
+        if item.children.is_empty() {
+            let marker = f.allocator().alloc_concat_strs_array([&prefix, checkbox]);
+            write!(f, text(marker.trim_end()));
+            continue;
+        }
+
+        let prefix: &'a str = f.allocator().alloc_str(&prefix);
+        write!(f, text(prefix));
+
+        // A `[paragraph, html]` item whose html sits left of the content column is
+        // micromark's lazy type 7 quirk (parser DIVERGENCES): the html stays where it was, unaligned.
+        // (Prettier drops the alignment whenever the two columns differ,
+        // which moves an html block indented past a task checkbox out of the item:
+        // DIVERGENCES `list-indented-code-alignment`)
+        let skip_align =
+            item.children.len() == 2 && matches!(item.children[1], Block::HtmlBlock(_)) && {
+                let source = f.context().source_text().as_str();
+                let content_column = item
+                    .checkbox
+                    .map_or(item.children[0].span().start, |checkbox| checkbox.span.start);
+                column_of(source, item.children[1].span().start) < column_of(source, content_column)
+            };
+        let body = format_with(|f| write_list_item(item, checkbox, prefix.len(), loose, f));
+        let width = if skip_align { 0 } else { u8::try_from(prefix.len()).unwrap_or(u8::MAX) };
+        // The item's content column is the root that verbatim continuation lines return to
+        write!(f, align(width, &mark_as_root(&body)));
+    }
+
+    f.context().lists().borrow_mut().pop();
+}
+
+fn write_list_item<'a>(
+    item: &'a ListItem<'a>,
+    checkbox: &'static str,
+    list_prefix_len: usize,
+    loose: bool,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) {
+    write!(f, token(checkbox));
+
+    // Non-first children (and a first child that is a list) sit `tabWidth - prefix` further in,
+    // capped at 3 (4+ would read as indented code).
+    let indent_width = usize::from(f.options().indent_width.value());
+    let alignment = indent_width.saturating_sub(list_prefix_len).min(3);
+    let parent = block::Parent::ListItem { loose, after_checkbox: false };
+
+    for (i, child) in item.children.iter().enumerate() {
+        if i > 0 {
+            block::write_gap(&item.children, i, parent, f);
+        }
+        // The first block follows the checkbox on its line: its first line is not a line start
+        let child_parent = if i == 0 && !checkbox.is_empty() {
+            block::Parent::ListItem { loose, after_checkbox: true }
+        } else {
+            parent
+        };
+        let body = format_with(|f| block::write_block(child, &item.children, i, child_parent, f));
+        // An indented code block's content is whatever follows the item's content column + 4:
+        // any extra alignment lands inside the code on the next parse.
+        // See DIVERGENCES `list-indented-code-alignment`.
+        // (Prettier's checkbox align before #19647, the same for prettier/prettier#19986)
+        if is_indented_code(child) || matches!(child, Block::HtmlBlock(_)) {
+            write!(f, body);
+            continue;
+        }
+        // The first child (unless a list) sits right after the checkbox;
+        // other children get the tab-width alignment.
+        // `checkbox` is `[x] ` / `[ ] ` / empty, `alignment` is at most 3
+        #[expect(clippy::cast_possible_truncation)]
+        let (checkbox_width, alignment_width) = (checkbox.len() as u8, alignment as u8);
+        if i == 0 && !matches!(child, Block::List(_)) {
+            write!(f, align(checkbox_width, &body));
+        } else {
+            write!(f, [token(&"   "[..alignment]), align(alignment_width, &body)]);
+        }
+    }
+}
+
+/// Loose: spread, or a blank line before the next item.
+fn is_loose_item(
+    item: &ListItem<'_>,
+    next: Option<&ListItem<'_>>,
+    f: &MarkdownFormatter<'_, '_>,
+) -> bool {
+    item.spread
+        || next.is_some_and(|next| f.context().has_blank_between(item.span.end, next.span.start))
+}
+
+/// Whether this list prints the alternate marker (`*` / `)`).
+///
+/// Adjacent lists of the same kind alternate markers so they stay separate lists.
+/// A list kept verbatim (`prettier-ignore`) shows its own marker,
+/// so when it opens the run the alternation continues from that marker rather than from the default.
+fn uses_alternate_marker(
+    list: &List<'_>,
+    siblings: &[Block<'_>],
+    index: usize,
+    f: &MarkdownFormatter<'_, '_>,
+) -> bool {
+    let ordered = is_ordered(list);
+    let same_kind = |block: &Block<'_>| matches!(block, Block::List(other) if matches!(other.marker, ListMarker::Ordered { .. }) == ordered);
+    let mut start = index;
+    while start > 0 && same_kind(&siblings[start - 1]) {
+        start -= 1;
+    }
+    // Only the run's first list can be verbatim:
+    // an ignore comment before any later one would sit between two lists and end the run.
+    let first_alternate = match &siblings[start] {
+        Block::List(first) if block::is_ignored(siblings, start, f) => match first.marker {
+            ListMarker::Bullet { marker } => marker == b'*',
+            ListMarker::Ordered { delimiter } => delimiter == b')',
+        },
+        _ => false,
+    };
+    first_alternate ^ ((index - start) % 2 == 1)
+}
+
+/// The item's number, leading zeros dropped.
+fn marker_number(item: &ListItem<'_>, f: &MarkdownFormatter<'_, '_>) -> u64 {
+    lexical::ordered_number(f.context().slice(item.marker)).map_or(0, u64::from)
+}
+
+/// `1. 1. 1.` (or `0. 1. 1.`) numbering: every item keeps `1` so edits do not renumber the rest.
+fn has_git_diff_friendly_ordered_list(list: &List<'_>, f: &MarkdownFormatter<'_, '_>) -> bool {
+    if !is_ordered(list) || list.children.len() < 2 {
+        return false;
+    }
+    if marker_number(&list.children[1], f) != 1 {
+        return false;
+    }
+    if marker_number(&list.children[0], f) != 0 {
+        return true;
+    }
+    list.children.get(2).is_some_and(|third| marker_number(third, f) == 1)
+}
+
+/// Whether ordered markers are padded to the tab width.
+fn is_aligned(list: &List<'_>, next: Option<&Block<'_>>, f: &MarkdownFormatter<'_, '_>) -> bool {
+    if list.children.is_empty() {
+        return false;
+    }
+    // An unaligned ancestor list makes every descendant unaligned
+    // (each frame carries its ancestors' verdict)
+    if f.context().lists().borrow().last().is_some_and(|frame| !frame.aligned) {
+        return false;
+    }
+    // Hard to align when followed by indented code
+    if next.is_some_and(is_indented_code) {
+        return false;
+    }
+    if !is_ordered(list) {
+        return true;
+    }
+    // An item starting with indented code has its content column fixed at the marker plus one space:
+    // padding the marker would land inside the code (`>2.     foo`,
+    // where the code starts at a tab stop only because of the `>`).
+    // See DIVERGENCES `list-indented-code-alignment`.
+    if list.children.iter().any(|item| item.children.first().is_some_and(is_indented_code)) {
+        return false;
+    }
+
+    let source = f.context().source_text().as_str();
+    let item_start = |item: &ListItem<'_>| -> Option<usize> {
+        item.children.first().map(|child| column_of(source, child.span().start))
+    };
+    let indent_width = usize::from(f.options().indent_width.value());
+
+    let first = &list.children[0];
+    if first.padding > 1 {
+        return true;
+    }
+    let Some(first_start) = item_start(first) else { return false };
+    // `x % 0` is `NaN` in Prettier, never equal to 0
+    let at_tab_stop = |column: usize| indent_width != 0 && column.is_multiple_of(indent_width);
+    let Some(second) = list.children.get(1) else {
+        return at_tab_stop(first_start);
+    };
+    if item_start(second) != Some(first_start) {
+        return false;
+    }
+    if at_tab_stop(first_start) {
+        return true;
+    }
+    second.padding > 1
+}
+
+/// Pads the prefix so the content starts at a tab stop
+/// (never 4+ extra: that would be indented code).
+fn align_list_prefix(prefix: &mut String, indent_width: usize) {
+    if indent_width == 0 {
+        return;
+    }
+    let rest = prefix.len() % indent_width;
+    let additional = if rest == 0 { 0 } else { indent_width - rest };
+    if additional < 4 {
+        prefix.extend(std::iter::repeat_n(' ', additional));
+    }
+}
+
+/// A list followed by an indented code block must indent its content deeper than the code
+/// (4 + the code's own leading whitespace + 1), or the code would join the list.
+fn required_indent(next: Option<&Block<'_>>, f: &MarkdownFormatter<'_, '_>) -> usize {
+    let Some(Block::CodeBlock(code)) = next else { return 0 };
+    if !matches!(code.kind, CodeBlockKind::Indented) {
+        return 0;
+    }
+    let Some(first) = code.lines.first() else { return 0 };
+    let raw = f.context().slice(first.span);
+    let leading: usize = raw
+        .bytes()
+        .take_while(|b| matches!(b, b' ' | b'\t'))
+        .map(|b| if b == b'\t' { 4 } else { 1 })
+        .sum();
+    4 + usize::from(first.padding) + leading + 1
+}
+
+/// Pads the prefix to `min_indent`:
+/// trailing spaces first (max 4), then leading spaces (max 3).
+fn pad_to_min_indent(prefix: &mut String, min_indent: usize) {
+    if prefix.len() >= min_indent {
+        return;
+    }
+    let trimmed_len = prefix.trim_end().len();
+    prefix.truncate(trimmed_len);
+    let trailing = (min_indent - prefix.len()).min(4);
+    prefix.extend(std::iter::repeat_n(' ', trailing));
+    let leading = min_indent.saturating_sub(prefix.len()).min(3);
+    if leading > 0 {
+        prefix.insert_str(0, &" ".repeat(leading));
+    }
+}
diff --git a/crates/oxc_formatter_markdown/src/print/mod.rs b/crates/oxc_formatter_markdown/src/print/mod.rs
new file mode 100644
index 0000000000..03a8841f8b
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/mod.rs
@@ -0,0 +1,177 @@
+use std::{borrow::Cow, cell::Cell};
+
+use oxc_allocator::StringBuilder;
+use oxc_formatter_core::{
+    Buffer, Format, Formatter,
+    builders::{FormatWith, Line, empty_line, exact_line_breaks, hard_line_break, text, token},
+    write,
+};
+use oxc_markdown_parser::{Segment, Span, ast::Root};
+
+use crate::context::MarkdownFormatContext;
+
+mod block;
+mod blockquote;
+mod cjk;
+mod code;
+mod escape;
+mod inline;
+mod line_shape;
+mod link;
+mod list;
+mod pairing;
+pub use pairing::Mark;
+mod parts;
+mod table;
+mod text;
+
+pub type MarkdownFormatter<'buf, 'a> = Formatter<'buf, 'a, MarkdownFormatContext<'a>>;
+
+/// `Format` impl for `&'static str` specialized to `MarkdownFormatContext`.
+///
+/// Hardcoded to `MarkdownFormatContext` rather than generic over `C` so the blanket
+/// `&T where T: Format` doesn't overlap.
+impl<'a> Format<'a, MarkdownFormatContext<'a>> for &'static str {
+    #[inline]
+    fn fmt(&self, f: &mut MarkdownFormatter<'_, 'a>) {
+        write!(f, token(self));
+    }
+}
+
+/// Wraps a re-entrant Markdown closure in a [`FormatWith`].
+/// The closure's context is pinned to [`MarkdownFormatContext`] so call sites don't have to annotate it.
+#[inline]
+pub const fn format_with<'a, T>(formatter: T) -> FormatWith<T>
+where
+    T: Fn(&mut MarkdownFormatter<'_, 'a>),
+{
+    FormatWith::new(formatter)
+}
+
+pub fn write_root<'a>(root: &'a Root<'a>, f: &mut MarkdownFormatter<'_, 'a>) {
+    block::write_blocks(&root.children, block::Parent::Root, f);
+}
+
+/// Runs `body` with one of the context's depth counters incremented.
+/// The pairing is structural, so an early return inside `body` cannot leave the counter off.
+pub fn with_depth<'a>(
+    f: &mut MarkdownFormatter<'_, 'a>,
+    counter: for<'c> fn(&'c MarkdownFormatContext<'a>) -> &'c Cell<u32>,
+    body: impl FnOnce(&mut MarkdownFormatter<'_, 'a>),
+) {
+    let cell = counter(f.context());
+    cell.set(cell.get() + 1);
+    body(f);
+    let cell = counter(f.context());
+    cell.set(cell.get() - 1);
+}
+
+/// Emits the source slice as-is (`prettier-ignore`, constructs not printed yet).
+///
+/// The source is normalized to `\n` before parsing, so the slice is safe for the IR;
+/// a multi-line `text` prints its embedded newlines literally,
+/// so inside a blockquote the continuation lines keep the `>` markers they carry in the source (as Prettier's slices do).
+/// The trailing line ending belongs to the sibling separator, not to the block.
+pub fn write_verbatim(span: Span, f: &mut MarkdownFormatter<'_, '_>) {
+    write!(f, text(f.context().slice(span).trim_end_matches('\n')));
+}
+
+/// Emits `lines` one per output line, `separator` between them.
+///
+/// `hard_line_break` collapses consecutive breaks, so callers pass `exact_line_breaks(1)` (re-indents)
+/// or `literal_line_break` (root-anchored, keeps trailing whitespace).
+/// An empty line emits no text, so its indention stays pending and never prints.
+pub fn write_lines<'a>(
+    lines: impl IntoIterator<Item = &'a str>,
+    separator: Line,
+    f: &mut MarkdownFormatter<'_, 'a>,
+) {
+    for (i, line) in lines.into_iter().enumerate() {
+        if i > 0 {
+            write!(f, separator);
+        }
+        if !line.is_empty() {
+            write!(f, text(line));
+        }
+    }
+}
+
+/// [`write_lines`] with re-indenting breaks.
+/// Trailing spaces and tabs go, as Prettier's printer trims them before each hard line break.
+pub fn write_indented_lines<'a>(value: &'a str, f: &mut MarkdownFormatter<'_, 'a>) {
+    write_lines(
+        value.split('\n').map(|line| line.trim_end_matches([' ', '\t'])),
+        exact_line_breaks(1),
+        f,
+    );
+}
+
+/// The separator between two sibling blocks: a blank line, or just a line break.
+pub fn write_gap(blank: bool, f: &mut MarkdownFormatter<'_, '_>) {
+    if blank {
+        write!(f, empty_line());
+    } else {
+        write!(f, hard_line_break());
+    }
+}
+
+/// The logical text of a multi-line construct (`Segment::join`), in the arena when it has to be built.
+pub fn join_pieces<'a>(pieces: &[Segment], f: &MarkdownFormatter<'_, 'a>) -> &'a str {
+    let source = f.context().source_text().as_str();
+    match pieces {
+        [single] if single.padding == 0 => single.span.slice(source),
+        _ => {
+            let len = pieces
+                .iter()
+                .map(|p| (p.span.end - p.span.start) as usize + usize::from(p.padding) + 1)
+                .sum();
+            let mut out = StringBuilder::with_capacity_in(len, f.allocator());
+            for (i, piece) in pieces.iter().enumerate() {
+                if i > 0 {
+                    out.push('\n');
+                }
+                for _ in 0..piece.padding {
+                    out.push(' ');
+                }
+                out.push_str(piece.span.slice(source));
+            }
+            out.into_str()
+        }
+    }
+}
+
+/// 0-based column of `offset`, in bytes:
+/// the only prefixes that lead a line are container markers and ASCII whitespace,
+/// where bytes == characters.
+pub fn column_of(source: &str, offset: u32) -> usize {
+    source.as_bytes()[..offset as usize].iter().rev().take_while(|&&b| b != b'\n').count()
+}
+
+/// The longest run of `ch` in `text`.
+pub fn max_run(text: &str, ch: u8) -> usize {
+    let mut max = 0;
+    let mut run = 0;
+    for &b in text.as_bytes() {
+        if b == ch {
+            run += 1;
+            max = max.max(run);
+        } else {
+            run = 0;
+        }
+    }
+    max
+}
+
+/// Word separators: space, tab, newline.
+pub fn is_split_whitespace(c: char) -> bool {
+    matches!(c, '\t' | '\n' | ' ')
+}
+
+/// HTML whitespace: `\t\n\f\r` and space.
+pub const HTML_WHITESPACE: [char; 5] = ['\t', '\n', '\u{c}', '\r', ' '];
+
+/// `n` backticks; borrowed from a static run for every realistic length.
+pub fn backticks(n: usize) -> Cow<'static, str> {
+    const RUN: &str = "````````````````````````````````";
+    if n <= RUN.len() { Cow::Borrowed(&RUN[..n]) } else { Cow::Owned("`".repeat(n)) }
+}
diff --git a/crates/oxc_formatter_markdown/src/print/pairing.rs b/crates/oxc_formatter_markdown/src/print/pairing.rs
new file mode 100644
index 0000000000..c3e60ff0e2
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/pairing.rs
@@ -0,0 +1,105 @@
+//! Delimiter pairing check: the parser's resolver run on the text about to be printed.
+//!
+//! Marker normalization (`_` to `*`, `__` to `**`) and line joining change the neighbors of every
+//! `*` / `_` / `~` run, and with them which runs pair (flanking, the rule of three, family order).
+//! Instead of predicting that, the printed text is tokenized into runs and handed to
+//! `oxc_markdown_parser::attention::pairs`; the result must be the tree being printed.
+//! When it is not, the paragraph is printed again with its markers as written.
+
+use oxc_markdown_parser::{
+    Constructs,
+    attention::{Pair, Run, pairs},
+    escapes_next,
+};
+
+/// A printed-offset annotation recorded while collecting phrasing content.
+#[derive(Clone, Copy, Debug)]
+pub enum Mark {
+    /// An emphasis / strong / strikethrough node: the offsets of its opening and closing marker.
+    Delimiter { open: u32, close: u32, strong: bool },
+    /// Text whose delimiter characters never pair (code span, HTML, autolink, math, ...).
+    Opaque { start: u32, end: u32 },
+    /// A link's text: its runs resolve on their own (bracket level).
+    Group { start: u32, end: u32 },
+}
+
+/// A delimiter run of the printed text: where it is, and which group it resolves in.
+struct PrintedRun {
+    at: u32,
+    run: Run,
+    group: usize,
+}
+
+/// Whether the runs of `flat` (the printed text) form exactly the nodes in `marks`.
+pub fn consistent(flat: &str, marks: &[Mark]) -> bool {
+    let constructs = Constructs::markdown();
+    let to_u32 = |n: usize| u32::try_from(n).unwrap_or(u32::MAX);
+    // The whole text is the outermost group; a run or a node belongs to the innermost one
+    let mut groups: Vec<(u32, u32)> = vec![(0, to_u32(flat.len()))];
+    groups.extend(marks.iter().filter_map(|m| match m {
+        Mark::Group { start, end } => Some((*start, *end)),
+        _ => None,
+    }));
+    let group_of = |offset: u32| -> usize {
+        groups
+            .iter()
+            .enumerate()
+            .filter(|(_, (start, end))| *start <= offset && offset < *end)
+            .min_by_key(|(_, (start, end))| end - start)
+            .map_or(0, |(i, _)| i)
+    };
+
+    // Every run outside opaque text (recorded in print order, so a cursor suffices), escapes skipped
+    let mut opaque = marks.iter().filter_map(|m| match m {
+        Mark::Opaque { start, end } => Some((*start, *end)),
+        _ => None,
+    });
+    let mut next_opaque = opaque.next();
+    let bytes = flat.as_bytes();
+    let mut runs: Vec<PrintedRun> = Vec::new();
+    let mut i = 0;
+    while i < bytes.len() {
+        let at = to_u32(i);
+        if let Some((start, end)) = next_opaque
+            && at >= start
+        {
+            i = i.max(end as usize);
+            next_opaque = opaque.next();
+            continue;
+        }
+        match bytes[i] {
+            b'\\' if escapes_next(bytes, i) => i += 2,
+            marker @ (b'*' | b'_' | b'~') => {
+                let len = bytes[i..].iter().take_while(|&&b| b == marker).count();
+                let prev = flat[..i].chars().next_back();
+                let next = flat[i + len..].chars().next();
+                let run = Run::new(marker, len, prev, next, &constructs);
+                runs.push(PrintedRun { at, run, group: group_of(at) });
+                i += len;
+            }
+            _ => i += 1,
+        }
+    }
+
+    for group in 0..groups.len() {
+        let members: Vec<&PrintedRun> = runs.iter().filter(|r| r.group == group).collect();
+        let index_of = |offset: u32| -> Option<usize> {
+            members.iter().position(|r| r.at <= offset && offset < r.at + to_u32(r.run.len))
+        };
+        let mut expected: Vec<Pair> = marks
+            .iter()
+            .filter_map(|m| match *m {
+                Mark::Delimiter { open, close, strong } if group_of(open) == group => {
+                    Some(Pair { opener: index_of(open)?, closer: index_of(close)?, strong })
+                }
+                _ => None,
+            })
+            .collect();
+        expected.sort_unstable();
+        let group_runs: Vec<Run> = members.iter().map(|r| r.run).collect();
+        if pairs(&group_runs, group != 0) != expected {
+            return false;
+        }
+    }
+    true
+}
diff --git a/crates/oxc_formatter_markdown/src/print/parts.rs b/crates/oxc_formatter_markdown/src/print/parts.rs
new file mode 100644
index 0000000000..5287d0c7f5
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/parts.rs
@@ -0,0 +1,194 @@
+//! The fill of one phrasing content: every whitespace that may break is a separator,
+//! everything else (words, markers, code spans, hard breaks) is content.
+
+use oxc_allocator::{Allocator, ArenaVec, StringBuilder};
+use oxc_formatter_core::{
+    Buffer, Format,
+    builders::{
+        dedent_to_root, hard_line_break, literal_line_break, mark_as_root, soft_line_break,
+        soft_line_break_or_space, text,
+    },
+    write,
+};
+
+use crate::{context::MarkdownFormatContext, print::Mark};
+
+use super::{MarkdownFormatter, format_with};
+
+/// A piece of fill content.
+#[derive(Clone, Copy)]
+pub enum Atom<'a> {
+    Str(&'a str),
+    /// A forced break inside content (backslash hard break), not a separator:
+    /// a fill measures an item only up to a hard break,
+    /// so the first two words after one always share a line, whatever the width (Prettier does the same).
+    HardLine,
+    /// A line break that keeps trailing whitespace and resumes at the current indention (two-space hard break).
+    LiteralLine,
+    /// A line break inside a verbatim inline construct (HTML, liquid, code span):
+    /// the next line resumes at the container's content column, the only indention the parser strips.
+    VerbatimLine,
+}
+
+impl<'a> Format<'a, MarkdownFormatContext<'a>> for Atom<'a> {
+    fn fmt(&self, f: &mut MarkdownFormatter<'_, 'a>) {
+        match self {
+            Atom::Str(s) => write!(f, text(s)),
+            Atom::LiteralLine => write!(f, mark_as_root(&literal_line_break())),
+            // Containers mark their content column as root; a list item's extra alignment
+            // (checkbox, tab width) is not stripped by the parser and must not be printed here
+            Atom::VerbatimLine => write!(f, dedent_to_root(&hard_line_break())),
+            Atom::HardLine => write!(f, hard_line_break()),
+        }
+    }
+}
+
+/// A fill separator.
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Sep {
+    /// A break or nothing (a line break between CJ characters).
+    SoftLine,
+    Line,
+    HardLine,
+}
+
+impl<'a> Format<'a, MarkdownFormatContext<'a>> for Sep {
+    fn fmt(&self, f: &mut MarkdownFormatter<'_, 'a>) {
+        match self {
+            Sep::SoftLine => write!(f, soft_line_break()),
+            Sep::Line => write!(f, soft_line_break_or_space()),
+            Sep::HardLine => write!(f, hard_line_break()),
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+enum Item<'a> {
+    Atom(Atom<'a>),
+    Sep(Sep),
+}
+
+/// The alternating content / separator list of one fill, flat (no per-word allocation);
+/// runs of atoms are grouped when the fill is written.
+pub struct Parts<'a> {
+    items: ArenaVec<'a, Item<'a>>,
+    /// Bytes of `flat` pushed so far: the printed offset of what comes next.
+    len: u32,
+    /// The delimiter nodes, opaque text and link texts pushed, by printed offset (`pairing`).
+    pub marks: Vec<Mark>,
+}
+
+impl<'a> Item<'a> {
+    /// The item as the parser will read it: a break is a newline, a soft line between CJ letters nothing.
+    fn flat(&self) -> &'a str {
+        match self {
+            Item::Atom(Atom::Str(s)) => s,
+            Item::Atom(_) | Item::Sep(Sep::HardLine) => "\n",
+            Item::Sep(Sep::Line) => " ",
+            Item::Sep(Sep::SoftLine) => "",
+        }
+    }
+}
+
+impl<'a> Parts<'a> {
+    pub fn new(allocator: &'a Allocator) -> Self {
+        Self { items: ArenaVec::new_in(&allocator), len: 0, marks: Vec::new() }
+    }
+
+    pub fn len(&self) -> u32 {
+        self.len
+    }
+
+    pub fn push_str(&mut self, s: &'a str) {
+        // A raw newline in content resumes at column 0 (`push_lines` places continuation lines)
+        debug_assert!(!s.contains('\n'), "multi-line content must go through `push_lines`: {s:?}");
+        if !s.is_empty() {
+            self.push_atom(Atom::Str(s));
+        }
+    }
+
+    pub fn push_atom(&mut self, atom: Atom<'a>) {
+        self.push(Item::Atom(atom));
+    }
+
+    /// Adjacent separators collapse to the strongest (a text edge next to a soft break).
+    pub fn push_sep(&mut self, sep: Sep) {
+        if let Some(Item::Sep(existing)) = self.items.last_mut() {
+            *existing = (*existing).max(sep);
+        } else {
+            self.push(Item::Sep(sep));
+        }
+    }
+
+    fn push(&mut self, item: Item<'a>) {
+        self.len += u32::try_from(item.flat().len()).unwrap_or(u32::MAX);
+        self.items.push(item);
+    }
+
+    pub fn mark(&mut self, mark: Mark) {
+        self.marks.push(mark);
+    }
+
+    /// The content as the parser will read it.
+    pub fn flat(&self, allocator: &'a Allocator) -> &'a str {
+        let mut out = StringBuilder::with_capacity_in(self.len as usize, allocator);
+        for item in &self.items {
+            out.push_str(item.flat());
+        }
+        out.into_str()
+    }
+
+    /// `value` split into lines, `separator` between them.
+    pub fn push_lines(&mut self, value: &'a str, separator: Atom<'a>) {
+        for (i, line) in value.split('\n').enumerate() {
+            if i > 0 {
+                self.push_atom(separator);
+            }
+            self.push_str(line);
+        }
+    }
+
+    /// The content on one line (table cells): every separator is a space.
+    pub fn into_str(self, allocator: &'a Allocator) -> &'a str {
+        if let [Item::Atom(Atom::Str(s))] = self.items.as_slice() {
+            return s;
+        }
+        let mut out = StringBuilder::new_in(allocator);
+        for item in &self.items {
+            match item {
+                Item::Atom(Atom::Str(s)) => out.push_str(s),
+                _ => out.push(' '),
+            }
+        }
+        out.into_str()
+    }
+
+    pub fn write_fill(self, f: &mut MarkdownFormatter<'_, 'a>) {
+        let mut fill = f.fill();
+        let mut sep = Sep::Line;
+        let mut run_start = 0;
+        for (i, item) in self.items.iter().enumerate() {
+            if let Item::Sep(next) = item {
+                // A fill alternates content / separator;
+                // a separator with no content before it gets an empty entry.
+                let run = &self.items[run_start..i];
+                fill.entry(&sep, &format_with(|f| write_atoms(run, f)));
+                sep = *next;
+                run_start = i + 1;
+            }
+        }
+        if !self.items.is_empty() {
+            let run = &self.items[run_start..];
+            fill.entry(&sep, &format_with(|f| write_atoms(run, f)));
+        }
+        fill.finish();
+    }
+}
+
+fn write_atoms<'a>(items: &[Item<'a>], f: &mut MarkdownFormatter<'_, 'a>) {
+    for item in items {
+        if let Item::Atom(atom) = item {
+            atom.fmt(f);
+        }
+    }
+}
diff --git a/crates/oxc_formatter_markdown/src/print/table.rs b/crates/oxc_formatter_markdown/src/print/table.rs
new file mode 100644
index 0000000000..e5b221d366
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/table.rs
@@ -0,0 +1,120 @@
+//! GFM tables.
+//!
+//! Every cell is printed to a string first (Prettier's `printDocToString` at infinite width),
+//! then each column is padded to its widest cell (3 at least, the delimiter's `---`).
+//! With `proseWrap: never`, a table whose header row does not fit is printed compact instead.
+
+use oxc_allocator::{Allocator, ArenaVec, StringBuilder};
+use oxc_formatter_core::{
+    Buffer, TextWidth,
+    builders::{group, hard_line_break, if_group_breaks, if_group_fits_on_line},
+    format_args, write,
+};
+use oxc_markdown_parser::ast::{Table, TableAlign};
+
+use crate::options::ProseWrap;
+
+use super::{
+    MarkdownFormatter, format_with,
+    inline::{InlineParent, collect_phrasing},
+    write_lines,
+};
+
+struct Cell<'a> {
+    text: &'a str,
+    width: usize,
+}
+
+pub fn write_table<'a>(table: &'a Table<'a>, f: &mut MarkdownFormatter<'_, 'a>) {
+    let allocator = f.allocator();
+    let columns = table.children.iter().map(|row| row.children.len()).max().unwrap_or(0);
+    let mut widths = ArenaVec::from_iter_in(std::iter::repeat_n(3, columns), &allocator);
+    let mut rows = ArenaVec::with_capacity_in(table.children.len(), &allocator);
+    for row in &table.children {
+        let mut cells = ArenaVec::with_capacity_in(row.children.len(), &allocator);
+        for (i, cell) in row.children.iter().enumerate() {
+            let text =
+                collect_phrasing(&cell.children, InlineParent::default(), f).into_str(allocator);
+            let width = TextWidth::from_text(text, f.options().indent_width).value() as usize;
+            widths[i] = widths[i].max(width);
+            cells.push(Cell { text, width });
+        }
+        rows.push(cells);
+    }
+
+    let aligned = print_lines(&rows, &widths, &table.align, false, allocator);
+    if f.options().prose_wrap != ProseWrap::Never {
+        write_lines(aligned, hard_line_break(), f);
+        return;
+    }
+    // Only the header row is measured: `fits` stops at the first line break
+    let compact = print_lines(&rows, &widths, &table.align, true, allocator);
+    let separator = hard_line_break().without_expand_parent();
+    write!(
+        f,
+        group(&format_args!(
+            if_group_breaks(&format_with(|f| write_lines(compact.iter().copied(), separator, f))),
+            if_group_fits_on_line(&format_with(|f| write_lines(
+                aligned.iter().copied(),
+                separator,
+                f
+            ))),
+        ))
+    );
+}
+
+/// Header row, delimiter row, body rows.
+/// The delimiter row has the header's cell count (`align`): more, and it is not a table.
+fn print_lines<'a>(
+    rows: &[ArenaVec<'a, Cell<'a>>],
+    widths: &[usize],
+    align: &[TableAlign],
+    compact: bool,
+    allocator: &'a Allocator,
+) -> ArenaVec<'a, &'a str> {
+    let row_line = |cells: &[Cell<'a>]| {
+        let mut out = StringBuilder::with_capacity_in(
+            1 + widths.len() * 3 + widths.iter().sum::<usize>(),
+            allocator,
+        );
+        out.push('|');
+        for (i, cell) in cells.iter().enumerate() {
+            let spaces = if compact { 0 } else { widths[i] - cell.width };
+            let before = match align.get(i) {
+                Some(TableAlign::Right) => spaces,
+                Some(TableAlign::Center) => spaces / 2,
+                _ => 0,
+            };
+            out.push(' ');
+            out.push_ascii_byte_repeat(b' ', before);
+            out.push_str(cell.text);
+            out.push_ascii_byte_repeat(b' ', spaces - before);
+            out.push_str(" |");
+        }
+        out.into_str()
+    };
+    let delimiter_line = || {
+        let mut out = StringBuilder::new_in(allocator);
+        out.push('|');
+        for (align, width) in align.iter().zip(widths) {
+            let (first, last) = match align {
+                TableAlign::None => ('-', '-'),
+                TableAlign::Left => (':', '-'),
+                TableAlign::Center => (':', ':'),
+                TableAlign::Right => ('-', ':'),
+            };
+            out.push(' ');
+            out.push(first);
+            out.push_ascii_byte_repeat(b'-', if compact { 1 } else { width - 2 });
+            out.push(last);
+            out.push_str(" |");
+        }
+        out.into_str()
+    };
+
+    let mut lines = ArenaVec::with_capacity_in(rows.len() + 1, &allocator);
+    lines.push(row_line(&rows[0]));
+    lines.push(delimiter_line());
+    lines.extend(rows[1..].iter().map(|cells| row_line(cells)));
+    lines
+}
diff --git a/crates/oxc_formatter_markdown/src/print/text.rs b/crates/oxc_formatter_markdown/src/print/text.rs
new file mode 100644
index 0000000000..7b6b90d813
--- /dev/null
+++ b/crates/oxc_formatter_markdown/src/print/text.rs
@@ -0,0 +1,361 @@
+//! Words and whitespace.
+//!
+//! Text is printed RAW (escapes and entities as written);
+//! only the decisions below touch it:
+//! - `*` / `_` runs that could open or close emphasis get escaped inside emphasis / strong
+//! - a lone `===` / `---` word starting a line gets escaped (it would read as a setext underline)
+//! - a line break before a word that would start a block (`-`, `1.`, `#`, `>`) never breaks
+//!
+//! Around Chinese / Japanese text a whitespace follows Prettier's `printWhitespace`:
+//! a line break between CJ characters is not a space, and a space next to one never breaks
+//! (`cjk` classifies the word edges).
+
+use std::borrow::Cow;
+
+use oxc_formatter_core::arena_cow_str;
+use oxc_markdown_parser::{Constructs, lexical};
+
+use crate::options::ProseWrap;
+
+use super::{
+    MarkdownFormatter,
+    cjk::{self, Edge, Kind},
+    escape::{
+        ends_with_unescaped_backslash, is_fake_setext_underline, leading_run_escaped,
+        print_delimited_word,
+    },
+    is_split_whitespace,
+    line_shape::{is_line_shape_start, may_open_block},
+    parts::{Parts, Sep},
+};
+
+/// The word after a whitespace: the one a break there would put at a line start.
+#[derive(Clone, Copy)]
+pub struct NextWord<'a> {
+    pub word: &'a str,
+    /// The word is its text's only one.
+    pub alone_on_line: bool,
+    /// The word's leading `*` / `_` run gets escaped (inside emphasis):
+    /// printed, it starts with `\` and cannot open a block.
+    pub escaped: bool,
+}
+
+#[derive(Clone, Copy, Default)]
+pub struct TextContext<'a> {
+    /// Bytes at the text's start that extend the autolink literal before it
+    /// (its trailing punctuation stretch): an escape there changes the link.
+    pub autolink_stretch: usize,
+    /// The text is the first / last child of an `Emphasis` / `Strong`: its marker as printed.
+    pub first_of_delimiter: Option<u8>,
+    pub last_of_delimiter: Option<u8>,
+    /// The character right before / after the text as printed:
+    /// a space for a line break, the neighbor node's edge character, the enclosing marker;
+    /// `None` at a paragraph edge.
+    pub edge_prev: Option<char>,
+    pub edge_next: Option<char>,
+    /// The previous sibling is a soft break (the text starts a source line).
+    pub after_soft_break: bool,
+    /// The next sibling is a soft break (the text ends a source line).
+    pub before_soft_break: bool,
+    /// Nothing follows the text on its source line (a node glued after it would be part of the line).
+    pub ends_line: bool,
+    /// The first word the next sibling starts, for the whitespace that ends this text.
+    pub next_word: Option<NextWord<'a>>,
+    /// The text's last word with the nodes glued after it on the source line (`:-:` + `[[w]]`),
+    /// the word a break before it would put at a line start, and whether it ends the line.
+    pub glued_last_word: Option<(&'a str, bool)>,
+    /// The last word of the previous sibling text (a soft break's other side), for the CJK rules only;
+    /// a trailing `\` there was escaped by the text (see `push_text`).
+    pub prev_word: Option<&'a str>,
+    /// The sentence puts spaces between CJ and non-CJK words (Prettier's `usesCJSpaces`);
+    /// `None` when it has no CJK text at all.
+    pub cj_spaces: Option<bool>,
+    /// Inside a reference link's raw content, where a line break never prevents a break.
+    pub is_link: bool,
+}
+
+/// Splits `raw` into words and whitespace and pushes them, in one pass.
+pub fn push_text<'a>(
+    raw: &'a str,
+    cx: TextContext<'a>,
+    parts: &mut Parts<'a>,
+    f: &MarkdownFormatter<'_, 'a>,
+) {
+    // Markers printed as written need no escapes: the text pairs as the source did
+    let in_delimiter =
+        f.context().delimiter_depth().get() > 0 && !f.context().literal_markers().get();
+    let prose_wrap = f.options().prose_wrap;
+
+    let mut rest = raw;
+    let mut is_first = true;
+    let leading_ws = raw.starts_with(is_split_whitespace);
+    let mut prev_word: Option<&'a str> = None;
+    loop {
+        // Whitespace before the next word (leading, or the run after the previous word).
+        let after_ws = rest.trim_start_matches(is_split_whitespace);
+        let ws = &rest[..rest.len() - after_ws.len()];
+        rest = after_ws;
+        let word_end = rest.find(is_split_whitespace).unwrap_or(rest.len());
+        let (word, tail) = rest.split_at(word_end);
+        let is_last = tail.trim_start_matches(is_split_whitespace).is_empty();
+        if !ws.is_empty() {
+            let next = if word.is_empty() {
+                cx.next_word
+            } else {
+                let escaped = in_delimiter && {
+                    let prev = if is_first { cx.edge_prev } else { Some(' ') };
+                    let next = if is_last { cx.edge_next } else { Some(' ') };
+                    leading_run_escaped(word, prev, next)
+                };
+                let (word, alone) = match cx.glued_last_word {
+                    Some(glued) if is_last => glued,
+                    _ => (word, is_last && cx.ends_line),
+                };
+                Some(NextWord { word, alone_on_line: is_first && alone, escaped })
+            };
+            let cx = TextContext { next_word: next, prev_word, ..cx };
+            // A line break right after an unescaped `\` would be a hard break
+            // (the text's last word gets its `\` escaped instead, and may break)
+            if prev_word.is_some_and(ends_with_unescaped_backslash) {
+                parts.push_str(" ");
+            } else {
+                push_whitespace(ws.contains('\n'), &cx, parts, f);
+            }
+        }
+        if word.is_empty() {
+            break;
+        }
+        prev_word = Some(word);
+        let printed: Cow<'a, str> = if in_delimiter {
+            let prev = if is_first { cx.edge_prev } else { Some(' ') };
+            let next = if is_last { cx.edge_next } else { Some(' ') };
+            // A leading marker character would merge with the opening marker (`**foo*`)
+            let escape_leading =
+                is_first && !leading_ws && cx.first_of_delimiter == Some(word.as_bytes()[0]);
+            let autolink_stretch = if is_first { cx.autolink_stretch } else { 0 };
+            print_delimited_word(word, escape_leading, autolink_stretch, prev, next)
+        } else if prose_wrap == ProseWrap::Preserve
+            && is_first
+            && is_last
+            && !leading_ws
+            && cx.after_soft_break
+            && is_fake_setext_underline(word)
+        {
+            Cow::Owned(format!("\\{word}"))
+        } else {
+            Cow::Borrowed(word)
+        };
+        // A line ending with `\` is a hard break (the source had whitespace after it, which goes);
+        // a `\` right before the closing marker would escape the marker's first character
+        let printed: Cow<'a, str> = if is_last
+            && (cx.before_soft_break || cx.last_of_delimiter.is_some())
+            && ends_with_unescaped_backslash(&printed)
+        {
+            Cow::Owned(format!("{printed}\\"))
+        } else {
+            printed
+        };
+        parts.push_str(arena_cow_str(&printed, f));
+        rest = tail;
+        is_first = false;
+    }
+}
+
+/// The whitespace (a space run, or one holding a `newline`) between `cx.prev_word`
+/// and `cx.next_word` (`None`: the whitespace touches a node edge):
+/// a separator that may break, a space, or nothing.
+pub fn push_whitespace<'a>(
+    newline: bool,
+    cx: &TextContext<'a>,
+    parts: &mut Parts<'a>,
+    f: &MarkdownFormatter<'_, 'a>,
+) {
+    let options = f.options();
+    // A space only matters where it may become a break (`always`)
+    let prose_wrap = if !cx.is_link
+        && (newline || options.prose_wrap == ProseWrap::Always)
+        && prevents_break(newline, cx.next_word, options.prose_wrap)
+    {
+        ProseWrap::Never
+    } else {
+        options.prose_wrap
+    };
+
+    if prose_wrap == ProseWrap::Preserve && newline {
+        parts.push_sep(Sep::HardLine);
+        return;
+    }
+    // The CJK rules only apply to a sentence with CJK text
+    let (prev, next) = if cx.cj_spaces.is_some() {
+        (
+            cx.prev_word.and_then(|w| cjk::edges(w).map(|(_, last)| last)),
+            cx.next_word.and_then(|w| cjk::edges(w.word).map(|(first, _)| first)),
+        )
+    } else {
+        (None, None)
+    };
+    let can_be_space = !newline || line_break_can_be_space(prev, next, cx);
+    let breakable = prose_wrap == ProseWrap::Always
+        && f.context().no_wrap_depth().get() == 0
+        && is_breakable(prev, next, cx);
+    match (breakable, can_be_space) {
+        (true, true) => parts.push_sep(Sep::Line),
+        (true, false) => parts.push_sep(Sep::SoftLine),
+        (false, true) => parts.push_str(" "),
+        (false, false) => {}
+    }
+}
+
+/// Prettier's `lineBreakCanBeConvertedToSpace`.
+fn line_break_can_be_space(prev: Option<Edge>, next: Option<Edge>, cx: &TextContext<'_>) -> bool {
+    if cx.is_link {
+        return true;
+    }
+    let (Some(prev), Some(next)) = (prev, next) else { return true };
+    let latin_like = |kind: Kind| matches!(kind, Kind::NonCjk | Kind::KLetter);
+    // Between non-CJK / Korean words, or Korean and CJ, a line break is a space
+    if (latin_like(prev.kind) && latin_like(next.kind))
+        || matches!(
+            (prev.kind, next.kind),
+            (Kind::KLetter, Kind::CjLetter) | (Kind::CjLetter, Kind::KLetter)
+        )
+    {
+        return true;
+    }
+    // A delimiter run glued to a CJ character gains flanking it did not have (`」\n**` → `」**` closes);
+    // a space keeps it inert, as the line break did
+    if is_delimiter_char(prev.ch) || is_delimiter_char(next.ch) {
+        return true;
+    }
+    // Around CJK punctuation or between CJ letters it is nothing
+    if prev.kind == Kind::CjkPunctuation
+        || next.kind == Kind::CjkPunctuation
+        || (prev.kind == Kind::CjLetter && next.kind == Kind::CjLetter)
+    {
+        return false;
+    }
+    // Between CJ and non-CJK: a space next to ASCII punctuation (`:::` fences),
+    // nothing next to other punctuation (`〜`, `…`), else the sentence's own style.
+    if prev.ch.is_ascii_punctuation() || next.ch.is_ascii_punctuation() {
+        return true;
+    }
+    if prev.punctuation || next.punctuation {
+        return false;
+    }
+    cx.cj_spaces.unwrap_or(false)
+}
+
+/// `*` `_` `~` `` ` ``: runs of these pair up by flanking or by length, so their neighbors matter.
+fn is_delimiter_char(c: char) -> bool {
+    matches!(c, '*' | '_' | '~' | '`')
+}
+
+/// Prettier's `isBreakable` for a `" "` / `"\n"` whitespace under `always`.
+fn is_breakable(prev: Option<Edge>, next: Option<Edge>, cx: &TextContext<'_>) -> bool {
+    if cx.is_link {
+        return true;
+    }
+    let (Some(prev), Some(next)) = (prev, next) else { return true };
+    // Korean next to CJ breaks;
+    // anything else next to CJ never does (browsers turn the break into a space)
+    matches!(
+        (prev.kind, next.kind),
+        (Kind::KLetter, Kind::CjLetter) | (Kind::CjLetter, Kind::KLetter)
+    ) || !(prev.kind.is_cj() || next.kind.is_cj())
+}
+
+/// Prettier's `usesCJSpaces`, over the words of one sentence (the texts of a soft-break run):
+/// whether spaces outnumber nothing between CJ and non-CJK words.
+/// `words` yields each text's words with the whitespace before them (`None` for the first).
+pub fn uses_cj_spaces<'a>(texts: impl Iterator<Item = &'a str>) -> bool {
+    let (mut spaces, mut nothing) = (0u32, 0u32);
+    let counts = |a: Kind, b: Kind| {
+        matches!((a, b), (Kind::CjLetter, Kind::NonCjk) | (Kind::NonCjk, Kind::CjLetter))
+    };
+    for text in texts {
+        let mut prev_last: Option<Kind> = None;
+        let mut rest = text;
+        loop {
+            let after_ws = rest.trim_start_matches(is_split_whitespace);
+            let ws = &rest[..rest.len() - after_ws.len()];
+            rest = after_ws;
+            let word_end = rest.find(is_split_whitespace).unwrap_or(rest.len());
+            let (word, tail) = rest.split_at(word_end);
+            if word.is_empty() {
+                break;
+            }
+            let mut kinds = cjk::kinds(word);
+            let first = kinds.next().unwrap_or(Kind::NonCjk);
+            if let Some(prev) = prev_last
+                && !ws.is_empty()
+                && !ws.contains('\n')
+                && counts(prev, first)
+            {
+                spaces += 1;
+            }
+            let mut last = first;
+            for kind in kinds {
+                if counts(last, kind) {
+                    nothing += 1;
+                }
+                last = kind;
+            }
+            prev_last = Some(last);
+            rest = tail;
+        }
+    }
+    spaces > nothing
+}
+
+/// Never break before a word that would start a block.
+pub fn prevents_break(newline: bool, next: Option<NextWord<'_>>, prose_wrap: ProseWrap) -> bool {
+    let Some(next) = next else { return false };
+    if next.escaped {
+        return false;
+    }
+    // Under `preserve` lines stay where they are, so whether the word stands alone is known
+    if !looks_like_block_start(next, prose_wrap == ProseWrap::Preserve) {
+        return false;
+    }
+    // A lone `---` / `===` after a newline is going to be escaped as a fake setext underline instead
+    !(prose_wrap == ProseWrap::Preserve
+        && newline
+        && is_fake_setext_underline(next.word)
+        && next.alone_on_line)
+}
+
+/// The parser's line-start classification (`lexical::line_start`), asked about the word alone:
+/// list markers, `#`s, `>`, thematic breaks and setext underlines, fences, HTML and directive openers,
+/// table rows, footnote definitions.
+/// (Prettier tests `/^>|^(?:[*+-]|#{1,6}|\d+[).])$/` only, which is how a wrapped `<div>` or `***` opens a block.)
+fn looks_like_block_start(next: NextWord<'_>, exact: bool) -> bool {
+    // Asked about the line the wrap would produce:
+    // the word alone (`***` is a break, `-|-` a delimiter row)
+    // or the word with content after it (`- x` interrupts a paragraph where an empty `-` does not).
+    // `exact`: the word's position is known; otherwise it depends on the wrapping itself, so both count.
+    if !may_open_block(next.word.as_bytes()[0]) {
+        return false;
+    }
+    let constructs = Constructs::markdown();
+    if (!exact || next.alone_on_line) && lexical::line_start(&constructs, next.word, true).is_some()
+    {
+        return true;
+    }
+    if exact && next.alone_on_line {
+        return false;
+    }
+    // A dialect line shape at a line start is printed raw from then on: never create one
+    // (asked about the word alone, so a `:::` word counts even where `::: note` would be an opener)
+    if is_line_shape_start(next.word) {
+        return true;
+    }
+    let mut buf = [0u8; 64];
+    let len = next.word.len();
+    if len + 2 > buf.len() {
+        return false;
+    }
+    buf[..len].copy_from_slice(next.word.as_bytes());
+    buf[len..len + 2].copy_from_slice(b" x");
+    let line = std::str::from_utf8(&buf[..len + 2]).unwrap_or(next.word);
+    lexical::line_start(&constructs, line, true).is_some()
+}
diff --git a/crates/oxc_formatter_markdown/tests/conformance.rs b/crates/oxc_formatter_markdown/tests/conformance.rs
new file mode 100644
index 0000000000..80ac50e3d7
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/conformance.rs
@@ -0,0 +1,103 @@
+//! Prettier conformance for Markdown.
+//!
+//! Compares output against the Prettier suite's `tests/format/markdown` snapshots via `oxc_formatter_tests::conformance`;
+//! the failure report is pinned with `insta`.
+//!
+//! Debug a specific test: `PRETTIER_FILTER=<substring> cargo test -p oxc_formatter_markdown --test conformance -- --nocapture`
+
+use std::path::Path;
+
+use oxc_allocator::Allocator;
+use oxc_formatter_core::LineWidth;
+use oxc_formatter_markdown::{MarkdownFormatOptions, format};
+use oxc_formatter_tests::{
+    OptionSet,
+    conformance::{ConformanceConfig, run_conformance},
+};
+
+#[path = "fixtures/options.rs"]
+mod options;
+use options::apply_markdown_options;
+
+const CONFIG: ConformanceConfig = ConformanceConfig {
+    language: "markdown",
+    fixture_roots: &["markdown"],
+    exact_parser: Some("markdown"),
+    ignore: &[
+        // Cursor tracking is an editor feature, not formatting.
+        "markdown/cursor/",
+        // Exercises Prettier's plugin loader.
+        "markdown/broken-plugins/",
+        // Front matter and embedded languages need the dispatcher; covered by oxfmt's E2E conformance.
+        "markdown/front-matter/",
+        "markdown/yaml/",
+        "markdown/toml/",
+        "markdown/multiparser-css/",
+        "markdown/multiparser-js/",
+        "markdown/multiparser-json/",
+        "markdown/jsx-semi/",
+        // Prettier reads the leading `---` block as (empty) front matter and keeps it verbatim;
+        // CommonMark alone sees a thematic break + setext heading. Recovered with the front matter pre-pass.
+        "markdown/commonmark-test-suite/snippet: example-96.md",
+        "markdown/commonmark-test-suite/snippet: example-98.md",
+        // Fenced blocks whose only difference is Prettier formatting the embedded language (js / ts / css / json / html / markdown).
+        "markdown/blockquote/code.md",
+        // Also the `always`-only trailing `>` line: DIVERGENCES.md `ignored-block-trailing-quote-line`.
+        "markdown/blockquote/ignore-code.md",
+        "markdown/list/codeblock.md",
+        "markdown/list/parser-regression/issue-11202.md",
+        "markdown/markdown/real-world-case.md",
+        "markdown/markdown/test-case.md",
+        "markdown/code/0-indent-js.md",
+        "markdown/code/format.md",
+        "markdown/code/mdn-auth-api.md",
+        "markdown/code/mdn-background-1.md",
+        "markdown/code/mdn-background-2.md",
+        "markdown/code/mdn-background-3.md",
+        "markdown/code/mdn-background-4.md",
+        "markdown/code/mdn-background-5.md",
+        "markdown/code/mdn-background-6.md",
+        "markdown/code/mdn-background-7.md",
+        "markdown/code/mdn-background-8.md",
+        "markdown/code/mdn-background-9.md",
+        "markdown/code/mdn-filter-1.md",
+        "markdown/code/mdn-filter-2.md",
+        "markdown/code/mdn-font-face-1.md",
+        "markdown/code/mdn-font-face-2.md",
+        "markdown/code/mdn-grid-auto-columns.md",
+        "markdown/code/mdn-import.md",
+        "markdown/code/mdn-mask-image.md",
+        "markdown/code/mdn-padding-1.md",
+        "markdown/code/mdn-padding-2.md",
+        "markdown/code/mdn-transform.md",
+        "markdown/code/mdn-unicode-range.md",
+        "markdown/code/ts-trailing-comma.md",
+        "markdown/code/angular/",
+        "markdown/code/lwc/",
+    ],
+    skip_spec: None,
+};
+
+fn parse_options(spec: &OptionSet) -> MarkdownFormatOptions {
+    // Prettier's default `printWidth` is 80 (oxc defaults to 100); the spec's own
+    // `printWidth`/`tabWidth`/`useTabs`/`endOfLine` then override inside `apply_markdown_options`.
+    let mut options = MarkdownFormatOptions {
+        line_width: LineWidth::try_from(80).unwrap(),
+        ..MarkdownFormatOptions::default()
+    };
+    apply_markdown_options(&mut options, spec);
+    options
+}
+
+fn format_markdown(_path: &Path, source_text: &str, spec: &OptionSet) -> Option<String> {
+    let options = parse_options(spec);
+    let allocator = Allocator::default();
+    let formatted = format(&allocator, source_text, options).ok()?;
+    Some(formatted.print().ok()?.into_code())
+}
+
+#[test]
+fn prettier_conformance() {
+    let Some(report) = run_conformance(&CONFIG, format_markdown) else { return };
+    insta::assert_snapshot!("prettier-markdown", report);
+}
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/fingerprint.rs b/crates/oxc_formatter_markdown/tests/fixtures/fingerprint.rs
new file mode 100644
index 0000000000..7bbe4d8056
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/fingerprint.rs
@@ -0,0 +1,344 @@
+//! Semantic fingerprint: what formatting must leave unchanged.
+//!
+//! Idempotency (`format(format(x)) == format(x)`) only says the output is stable;
+//! a corrupted output is often a fixpoint (a list that became a paragraph, an escape that became an entity).
+//! This walks the AST of the input and of the output and serializes the MEANING only,
+//! so `fingerprint(x) == fingerprint(format(x))` is `parse(format(x)) ≅ parse(x)`.
+//!
+//! Ignored, because formatting may change them:
+//! spans; the style facts this AST records and mdast does not (markers, fence chars, ATX vs setext,
+//! break kinds, indented vs fenced); text splitting and whitespace runs; list tightness / spread
+//! (Prettier's `massage-ast` drops `spread` / `isAligned` too, and collapses whitespace in labels and inline code).
+//!
+//! Compared, where Prettier's `massage-ast` looks away:
+//! - text content (decoded, whitespace collapsed): Prettier drops `text` nodes, which is where its escaping bugs hide
+//! - code block content: Prettier drops `code.value` because it formats the embedded language;
+//!   ours stays verbatim until embedding lands (then the content of dispatched languages gets exempted)
+//!
+//! Every entry is one line; nesting is indentation, so a mismatch reads as a diff.
+
+use std::fmt::Write as _;
+
+use cow_utils::CowUtils;
+
+use oxc_markdown_parser::{
+    Segment, Span,
+    ast::{
+        Block, CodeBlockKind, Inline, LinkKind, ListItem, ListMarker, ReferenceKind, Root,
+        TableAlign,
+    },
+    decode, label, lexical,
+};
+
+pub fn fingerprint(source: &str, root: &Root<'_>) -> String {
+    let mut w = Walker { source, out: String::new(), depth: 0 };
+    w.blocks(&root.children);
+    w.out
+}
+
+struct Walker<'s> {
+    source: &'s str,
+    out: String,
+    depth: usize,
+}
+
+impl Walker<'_> {
+    fn line(&mut self, s: &str) {
+        for _ in 0..self.depth {
+            self.out.push_str("  ");
+        }
+        self.out.push_str(s);
+        self.out.push('\n');
+    }
+
+    fn nested(&mut self, f: impl FnOnce(&mut Self)) {
+        self.depth += 1;
+        f(self);
+        self.depth -= 1;
+    }
+
+    fn raw(&self, span: Span) -> &str {
+        span.slice(self.source)
+    }
+
+    /// Verbatim lines; trailing spaces / tabs are a formatter freedom (dropped before every line break).
+    fn joined(&self, pieces: &[Segment]) -> String {
+        Segment::join(self.source, pieces)
+            .split('\n')
+            .map(|line| line.trim_end_matches([' ', '\t']))
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+
+    fn blocks(&mut self, blocks: &[Block<'_>]) {
+        for block in blocks {
+            self.block(block);
+        }
+    }
+
+    fn block(&mut self, block: &Block<'_>) {
+        match block {
+            Block::Paragraph(p) => {
+                let text = self.inlines(&p.children);
+                self.line(&format!("paragraph {text}"));
+            }
+            Block::Heading(h) => {
+                let text = self.inlines(&h.children);
+                self.line(&format!("heading {} {text}", h.level));
+            }
+            Block::ThematicBreak(_) => self.line("thematic-break"),
+            Block::CodeBlock(c) => {
+                // Fenced vs indented is a style fact; the info string and the content are not.
+                let info = match c.kind {
+                    // The info string is printed as `lang meta` with one space between;
+                    // escapes and entities are decoded like text.
+                    CodeBlockKind::Fenced { lang, meta, .. } => [lang, meta]
+                        .into_iter()
+                        .flatten()
+                        .map(|part| decode::decode(self.raw(part), true))
+                        .collect::<Vec<_>>()
+                        .join(" "),
+                    CodeBlockKind::Indented => String::new(),
+                };
+                let content = self.joined(&c.lines);
+                self.line(&format!("code [{info}] {content:?}"));
+            }
+            Block::HtmlBlock(h) => {
+                // Trailing blank lines of an unclosed block (type 1-5 at EOF) render as nothing
+                let content = self.joined(&h.lines);
+                let content = content.trim_end_matches('\n');
+                self.line(&format!("html {content:?}"));
+            }
+            Block::Blockquote(q) => {
+                self.line("blockquote");
+                self.nested(|w| w.blocks(&q.children));
+            }
+            Block::List(l) => {
+                let head = match l.marker {
+                    ListMarker::Bullet { .. } => "list bullet".to_string(),
+                    ListMarker::Ordered { .. } => {
+                        // Only the start number is semantic; the rest are renumbered freely
+                        let start = l
+                            .children
+                            .first()
+                            .and_then(|item| lexical::ordered_number(self.raw(item.marker)))
+                            .unwrap_or(1);
+                        format!("list ordered start={start}")
+                    }
+                };
+                self.line(&head);
+                self.nested(|w| {
+                    for item in &l.children {
+                        w.list_item(item);
+                    }
+                });
+            }
+            Block::Definition(d) => {
+                let label = label::normalize(&self.joined(&d.label)).into_owned();
+                let dest = decode::destination(self.source, &d.destination);
+                let title = d.title.as_ref().map(|t| decode::title(self.source, t));
+                self.line(&format!("definition [{label}] {dest} {title:?}"));
+            }
+            Block::Table(t) => {
+                let align: Vec<&str> = t
+                    .align
+                    .iter()
+                    .map(|a| match a {
+                        TableAlign::None => "-",
+                        TableAlign::Left => "l",
+                        TableAlign::Center => "c",
+                        TableAlign::Right => "r",
+                    })
+                    .collect();
+                self.line(&format!("table {}", align.join("")));
+                self.nested(|w| {
+                    for row in &t.children {
+                        let cells: Vec<String> =
+                            row.children.iter().map(|cell| w.inlines(&cell.children)).collect();
+                        w.line(&format!("row {cells:?}"));
+                    }
+                });
+            }
+            Block::FootnoteDefinition(fd) => {
+                let label = label::normalize(self.raw(fd.label)).into_owned();
+                self.line(&format!("footnote-definition [{label}]"));
+                self.nested(|w| w.blocks(&fd.children));
+            }
+            Block::MathBlock(m) => {
+                let meta = m.meta.map(|s| self.raw(s).to_string());
+                let content = self.joined(&m.lines);
+                self.line(&format!("math {meta:?} {content:?}"));
+            }
+            Block::Liquid(l) => {
+                let content = self.joined(&l.pieces);
+                self.line(&format!("liquid {content:?}"));
+            }
+            Block::ContainerDirective(d) => {
+                let opening = self.raw(d.opening).trim();
+                let closed = d.closing.is_some();
+                self.line(&format!("directive {opening:?} closed={closed}"));
+                self.nested(|w| w.blocks(&d.children));
+            }
+            Block::MdxEsm(n) => {
+                let raw = self.raw(n.span);
+                self.line(&format!("mdx-esm {raw:?}"));
+            }
+            Block::MdxExpression(n) => {
+                let raw = self.raw(n.span);
+                self.line(&format!("mdx-expression {raw:?}"));
+            }
+            Block::MdxJsx(j) => {
+                let opening = self.raw(j.opening);
+                self.line(&format!("mdx-jsx {opening:?}"));
+                self.nested(|w| w.blocks(&j.children));
+            }
+        }
+    }
+
+    fn list_item(&mut self, item: &ListItem<'_>) {
+        let head = match item.checkbox {
+            Some(c) if c.checked => "item [x]",
+            Some(_) => "item [ ]",
+            None => "item",
+        };
+        self.line(head);
+        self.nested(|w| w.blocks(&item.children));
+    }
+
+    /// Phrasing content as one string: texts concatenate, so how they were split does not matter.
+    fn inlines(&self, inlines: &[Inline<'_>]) -> String {
+        let mut out = String::new();
+        for inline in inlines {
+            self.inline(inline, &mut out);
+        }
+        collapse_whitespace(&out)
+    }
+
+    fn inline(&self, inline: &Inline<'_>, out: &mut String) {
+        match inline {
+            Inline::Text(t) => out.push_str(&decode::decode(self.raw(t.span), true)),
+            Inline::SoftBreak(_) => out.push(' '),
+            Inline::HardBreak(_) => out.push_str("<br>"),
+            Inline::Emphasis(e) => {
+                out.push_str("<em>");
+                for child in &e.children {
+                    self.inline(child, out);
+                }
+                out.push_str("</em>");
+            }
+            Inline::Strong(s) => {
+                out.push_str("<strong>");
+                for child in &s.children {
+                    self.inline(child, out);
+                }
+                out.push_str("</strong>");
+            }
+            Inline::Strikethrough(s) => {
+                out.push_str("<del>");
+                for child in &s.children {
+                    self.inline(child, out);
+                }
+                out.push_str("</del>");
+            }
+            Inline::CodeSpan(c) => {
+                // Prettier's massage: `\n` inside inline code is a space (whitespace is content here)
+                let content =
+                    Segment::join(self.source, &c.pieces).cow_replace('\n', " ").into_owned();
+                let _ = write!(out, "<code>{content}</code>");
+            }
+            Inline::Link(l) => {
+                out.push_str("<a ");
+                self.link_kind(&l.kind, out);
+                out.push('>');
+                for child in &l.children {
+                    self.inline(child, out);
+                }
+                out.push_str("</a>");
+            }
+            Inline::Image(i) => {
+                out.push_str("<img ");
+                self.link_kind(&i.kind, out);
+                out.push_str(" alt=");
+                for child in &i.children {
+                    self.inline(child, out);
+                }
+                out.push('>');
+            }
+            Inline::Autolink(a) => {
+                let _ = write!(out, "<autolink {}>", self.raw(a.span));
+            }
+            Inline::AutolinkLiteral(a) => out.push_str(self.raw(a.span)),
+            Inline::HtmlInline(h) => out.push_str(&self.joined(&h.pieces)),
+            Inline::FootnoteReference(r) => {
+                let _ = write!(out, "<sup [{}]>", label::normalize(self.raw(r.label)));
+            }
+            Inline::MathSpan(m) => out.push_str(&self.joined(&m.pieces)),
+            Inline::WikiLink(w) => out.push_str(self.raw(w.span)),
+            Inline::Liquid(l) => out.push_str(&self.joined(&l.pieces)),
+            Inline::MdxExpression(n) => out.push_str(self.raw(n.span)),
+            Inline::MdxJsx(j) => {
+                out.push_str(self.raw(j.opening));
+                for child in &j.children {
+                    self.inline(child, out);
+                }
+                if let Some(closing) = j.closing {
+                    out.push_str(self.raw(closing));
+                }
+            }
+        }
+    }
+
+    fn link_kind(&self, kind: &LinkKind<'_>, out: &mut String) {
+        match kind {
+            LinkKind::Inline { destination, title } => {
+                // `<dest>` vs bare is a style fact; the destination text is not.
+                let dest = decode::destination(self.source, destination);
+                let _ = write!(out, "href={dest}");
+                if let Some(title) = title {
+                    let _ = write!(out, " title={:?}", decode::title(self.source, title));
+                }
+            }
+            LinkKind::Reference { kind, label: pieces } => {
+                let kind = match kind {
+                    ReferenceKind::Full => "full",
+                    ReferenceKind::Collapsed => "collapsed",
+                    ReferenceKind::Shortcut => "shortcut",
+                };
+                let label = label::normalize(&self.joined(pieces)).into_owned();
+                let _ = write!(out, "ref={kind} [{label}]");
+            }
+        }
+    }
+}
+
+/// Whitespace runs are a formatter freedom (`proseWrap`, indentation), their content is not.
+/// A run touching a Chinese / Japanese character is nothing: the printer treats a space
+/// and a line break next to CJ text as interchangeable with no whitespace
+/// (browsers drop a segment break between CJ characters), so the oracle equates all three.
+fn collapse_whitespace(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    let mut pending_space = false;
+    for word in s.split_whitespace() {
+        if pending_space && !out.ends_with(is_cj) && !word.starts_with(is_cj) {
+            out.push(' ');
+        }
+        out.push_str(word);
+        pending_space = true;
+    }
+    out
+}
+
+/// Chinese / Japanese (not Korean) by Unicode block; deliberately not the printer's table.
+fn is_cj(c: char) -> bool {
+    matches!(u32::from(c),
+        0x2E80..=0x303F   // CJK radicals, Kangxi, ideographic description, CJK symbols and punctuation
+        | 0x3040..=0x30FF // Hiragana, Katakana
+        | 0x3100..=0x312F // Bopomofo
+        | 0x31C0..=0x31EF // CJK strokes
+        | 0x3200..=0x9FFF // enclosed CJK, compatibility, ext A, unified ideographs
+        | 0xF900..=0xFAFF // compatibility ideographs
+        | 0xFE30..=0xFE4F // compatibility forms
+        | 0xFF00..=0xFF9F // fullwidth forms, halfwidth katakana
+        | 0x20000..=0x3FFFF // ext B and beyond
+    )
+}
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/basic.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/basic.md
new file mode 100644
index 0000000000..2a29de7fd1
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/basic.md
@@ -0,0 +1,26 @@
+# Title
+
+A paragraph with *emphasis*, **strong**, `code` and a [link](https://example.com "title").
+
+- one
+- two
+  - nested
+
+1. first
+2. second
+
+> quoted
+
+```js
+const x = 1;
+```
+
+| a | b |
+| - | :-: |
+| 1 | 2 |
+
+---
+
+Text with a hard break  
+and a soft
+break.
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/basic.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/basic.md.snap
new file mode 100644
index 0000000000..72b3430fe8
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/basic.md.snap
@@ -0,0 +1,93 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+# Title
+
+A paragraph with *emphasis*, **strong**, `code` and a [link](https://example.com "title").
+
+- one
+- two
+  - nested
+
+1. first
+2. second
+
+> quoted
+
+```js
+const x = 1;
+```
+
+| a | b |
+| - | :-: |
+| 1 | 2 |
+
+---
+
+Text with a hard break  
+and a soft
+break.
+
+==================== Output ====================
+------------------
+{ printWidth: 80 }
+------------------
+# Title
+
+A paragraph with _emphasis_, **strong**, `code` and a [link](https://example.com "title").
+
+- one
+- two
+  - nested
+
+1. first
+2. second
+
+> quoted
+
+```js
+const x = 1;
+```
+
+| a   |  b  |
+| --- | :-: |
+| 1   |  2  |
+
+---
+
+Text with a hard break  
+and a soft
+break.
+
+-------------------
+{ printWidth: 100 }
+-------------------
+# Title
+
+A paragraph with _emphasis_, **strong**, `code` and a [link](https://example.com "title").
+
+- one
+- two
+  - nested
+
+1. first
+2. second
+
+> quoted
+
+```js
+const x = 1;
+```
+
+| a   |  b  |
+| --- | :-: |
+| 1   |  2  |
+
+---
+
+Text with a hard break  
+and a soft
+break.
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/indented-code-tab.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/indented-code-tab.md
new file mode 100644
index 0000000000..2336153290
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/indented-code-tab.md
@@ -0,0 +1,3 @@
+<!-- Indented code stays indented: two spaces and a tab are a 4-column indent too -->
+
+  	foo	baz		bim
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/indented-code-tab.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/indented-code-tab.md.snap
new file mode 100644
index 0000000000..0f92a8ee24
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/indented-code-tab.md.snap
@@ -0,0 +1,24 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- Indented code stays indented: two spaces and a tab are a 4-column indent too -->
+
+  	foo	baz		bim
+
+==================== Output ====================
+------------------
+{ printWidth: 80 }
+------------------
+<!-- Indented code stays indented: two spaces and a tab are a 4-column indent too -->
+
+    foo	baz		bim
+
+-------------------
+{ printWidth: 100 }
+-------------------
+<!-- Indented code stays indented: two spaces and a tab are a 4-column indent too -->
+
+    foo	baz		bim
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/link-url-special-chars.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/link-url-special-chars.md
new file mode 100644
index 0000000000..2ab1b6b12c
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/link-url-special-chars.md
@@ -0,0 +1,10 @@
+[paren](https://example.com/()foo->bar)
+[angle](<https://example.com/a b>)
+[backslash](https://example.com/a\b)
+[backslash-before-punct](https://example.com/a\\*b)
+[backslash-last](https://example.com/a\\)
+[entity](https://example.com/?a&amp;b)
+[title](https://example.com "a &amp; b")
+
+[def]: https://example.com/()balanced
+[def-unbalanced]: https://example.com/(unbalanced
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/link-url-special-chars.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/link-url-special-chars.md.snap
new file mode 100644
index 0000000000..a69d0caebd
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/link-url-special-chars.md.snap
@@ -0,0 +1,47 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+[paren](https://example.com/()foo->bar)
+[angle](<https://example.com/a b>)
+[backslash](https://example.com/a\b)
+[backslash-before-punct](https://example.com/a\\*b)
+[backslash-last](https://example.com/a\\)
+[entity](https://example.com/?a&amp;b)
+[title](https://example.com "a &amp; b")
+
+[def]: https://example.com/()balanced
+[def-unbalanced]: https://example.com/(unbalanced
+
+==================== Output ====================
+------------------
+{ printWidth: 80 }
+------------------
+[paren](<https://example.com/()foo-\>bar>)
+[angle](<https://example.com/a b>)
+[backslash](https://example.com/a\b)
+[backslash-before-punct](https://example.com/a\\*b)
+[backslash-last](https://example.com/a\\)
+[entity](https://example.com/?a&b)
+[title](https://example.com "a & b")
+
+[def]: https://example.com/()balanced
+
+[def-unbalanced]: https://example.com/(unbalanced
+
+-------------------
+{ printWidth: 100 }
+-------------------
+[paren](<https://example.com/()foo-\>bar>)
+[angle](<https://example.com/a b>)
+[backslash](https://example.com/a\b)
+[backslash-before-punct](https://example.com/a\\*b)
+[backslash-last](https://example.com/a\\)
+[entity](https://example.com/?a&b)
+[title](https://example.com "a & b")
+
+[def]: https://example.com/()balanced
+
+[def-unbalanced]: https://example.com/(unbalanced
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/list-multiline-inline.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/list-multiline-inline.md
new file mode 100644
index 0000000000..1f3a8779c1
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/list-multiline-inline.md
@@ -0,0 +1,20 @@
+<!-- Continuation lines of verbatim inline nodes resume at the container column (`- `, not the printed alignment), whitespace after it kept: it is content -->
+
+- [ ] a `x
+      y` b
+
+- [ ] **CI is green** - <!-- if any check is red or skipped, name it and say why. "Deploy" and
+      "Tear down PR preview" showing skipped is expected. -->
+
+- [ ] a $x
+      y$ b
+
+- [ ] ![alt
+      text](u) and [t](u "one
+      two")
+
+- Top-level:
+  - Sub-bullet wraps and contains
+    `someInlineCode(arg1, arg2,
+    arg3, arg4)` and continues with more text after the
+    code span closes.
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/list-multiline-inline.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/list-multiline-inline.md.snap
new file mode 100644
index 0000000000..85979bf0f3
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/list-multiline-inline.md.snap
@@ -0,0 +1,75 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- Continuation lines of verbatim inline nodes resume at the container column (`- `, not the printed alignment), whitespace after it kept: it is content -->
+
+- [ ] a `x
+      y` b
+
+- [ ] **CI is green** - <!-- if any check is red or skipped, name it and say why. "Deploy" and
+      "Tear down PR preview" showing skipped is expected. -->
+
+- [ ] a $x
+      y$ b
+
+- [ ] ![alt
+      text](u) and [t](u "one
+      two")
+
+- Top-level:
+  - Sub-bullet wraps and contains
+    `someInlineCode(arg1, arg2,
+    arg3, arg4)` and continues with more text after the
+    code span closes.
+
+==================== Output ====================
+------------------
+{ printWidth: 80 }
+------------------
+<!-- Continuation lines of verbatim inline nodes resume at the container column (`- `, not the printed alignment), whitespace after it kept: it is content -->
+
+- [ ] a `x
+      y` b
+
+- [ ] **CI is green** - <!-- if any check is red or skipped, name it and say why. "Deploy" and
+      "Tear down PR preview" showing skipped is expected. -->
+
+- [ ] a $x
+      y$ b
+
+- [ ] ![alt
+      text](u) and [t](u "one
+  two")
+
+- Top-level:
+  - Sub-bullet wraps and contains
+    `someInlineCode(arg1, arg2,
+    arg3, arg4)` and continues with more text after the
+    code span closes.
+
+-------------------
+{ printWidth: 100 }
+-------------------
+<!-- Continuation lines of verbatim inline nodes resume at the container column (`- `, not the printed alignment), whitespace after it kept: it is content -->
+
+- [ ] a `x
+      y` b
+
+- [ ] **CI is green** - <!-- if any check is red or skipped, name it and say why. "Deploy" and
+      "Tear down PR preview" showing skipped is expected. -->
+
+- [ ] a $x
+      y$ b
+
+- [ ] ![alt
+      text](u) and [t](u "one
+  two")
+
+- Top-level:
+  - Sub-bullet wraps and contains
+    `someInlineCode(arg1, arg2,
+    arg3, arg4)` and continues with more text after the
+    code span closes.
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/oxfmt-ignore.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/oxfmt-ignore.md
new file mode 100644
index 0000000000..0b7df01fab
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/oxfmt-ignore.md
@@ -0,0 +1,13 @@
+<!-- oxfmt-ignore -->
+*   kept   as   written
+
+- formatted
+
+<!-- oxfmt-ignore-start -->
+| a | b |
+| - | - |
+| 1 | 2 |
+<!-- oxfmt-ignore-end -->
+
+<!-- prettier-ignore -->
+*   also   kept
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/oxfmt-ignore.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/oxfmt-ignore.md.snap
new file mode 100644
index 0000000000..4322fafbbf
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/oxfmt-ignore.md.snap
@@ -0,0 +1,54 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- oxfmt-ignore -->
+*   kept   as   written
+
+- formatted
+
+<!-- oxfmt-ignore-start -->
+| a | b |
+| - | - |
+| 1 | 2 |
+<!-- oxfmt-ignore-end -->
+
+<!-- prettier-ignore -->
+*   also   kept
+
+==================== Output ====================
+------------------
+{ printWidth: 80 }
+------------------
+<!-- oxfmt-ignore -->
+*   kept   as   written
+
+- formatted
+
+<!-- oxfmt-ignore-start -->
+| a | b |
+| - | - |
+| 1 | 2 |
+<!-- oxfmt-ignore-end -->
+
+<!-- prettier-ignore -->
+*   also   kept
+
+-------------------
+{ printWidth: 100 }
+-------------------
+<!-- oxfmt-ignore -->
+*   kept   as   written
+
+- formatted
+
+<!-- oxfmt-ignore-start -->
+| a | b |
+| - | - |
+| 1 | 2 |
+<!-- oxfmt-ignore-end -->
+
+<!-- prettier-ignore -->
+*   also   kept
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/cjk.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/cjk.md
new file mode 100644
index 0000000000..9f512c0372
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/cjk.md
@@ -0,0 +1,23 @@
+<!-- Whitespace around Chinese / Japanese: a line break between CJ characters is nothing,
+     a space next to CJ text never breaks, Korean behaves like Latin -->
+
+日本語の文章は
+改行しても
+空白になりません。
+
+漢字と English の間に空白を置く文書では、改行も
+English の前で空白になります。
+
+漢字とEnglishの間に空白を置かない文書では、改行は
+Englishの前でも消えます。
+
+한국어는 라틴 문자처럼
+띄어쓰기로 단어를 나눕니다.
+
+営業時間は月〜
+金の9時〜
+18時です。詳しくは……
+後日お知らせします……
+
+括弧の前 (paren) と後ろ、ASCII 記号の
+:: 前後は空白になります。
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/cjk.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/cjk.md.snap
new file mode 100644
index 0000000000..5db6059793
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/cjk.md.snap
@@ -0,0 +1,156 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- Whitespace around Chinese / Japanese: a line break between CJ characters is nothing,
+     a space next to CJ text never breaks, Korean behaves like Latin -->
+
+日本語の文章は
+改行しても
+空白になりません。
+
+漢字と English の間に空白を置く文書では、改行も
+English の前で空白になります。
+
+漢字とEnglishの間に空白を置かない文書では、改行は
+Englishの前でも消えます。
+
+한국어는 라틴 문자처럼
+띄어쓰기로 단어를 나눕니다.
+
+営業時間は月〜
+金の9時〜
+18時です。詳しくは……
+後日お知らせします……
+
+括弧の前 (paren) と後ろ、ASCII 記号の
+:: 前後は空白になります。
+
+==================== Output ====================
+---------------------------------------
+{ printWidth: 80, proseWrap: "always" }
+---------------------------------------
+<!-- Whitespace around Chinese / Japanese: a line break between CJ characters is nothing,
+     a space next to CJ text never breaks, Korean behaves like Latin -->
+
+日本語の文章は改行しても空白になりません。
+
+漢字と English の間に空白を置く文書では、改行も English の前で空白になります。
+
+漢字とEnglishの間に空白を置かない文書では、改行はEnglishの前でも消えます。
+
+한국어는 라틴 문자처럼 띄어쓰기로 단어를 나눕니다.
+
+営業時間は月〜金の9時〜18時です。詳しくは……後日お知らせします……
+
+括弧の前 (paren) と後ろ、ASCII 記号の :: 前後は空白になります。
+
+----------------------------------------
+{ printWidth: 100, proseWrap: "always" }
+----------------------------------------
+<!-- Whitespace around Chinese / Japanese: a line break between CJ characters is nothing,
+     a space next to CJ text never breaks, Korean behaves like Latin -->
+
+日本語の文章は改行しても空白になりません。
+
+漢字と English の間に空白を置く文書では、改行も English の前で空白になります。
+
+漢字とEnglishの間に空白を置かない文書では、改行はEnglishの前でも消えます。
+
+한국어는 라틴 문자처럼 띄어쓰기로 단어를 나눕니다.
+
+営業時間は月〜金の9時〜18時です。詳しくは……後日お知らせします……
+
+括弧の前 (paren) と後ろ、ASCII 記号の :: 前後は空白になります。
+
+--------------------------------------
+{ printWidth: 80, proseWrap: "never" }
+--------------------------------------
+<!-- Whitespace around Chinese / Japanese: a line break between CJ characters is nothing,
+     a space next to CJ text never breaks, Korean behaves like Latin -->
+
+日本語の文章は改行しても空白になりません。
+
+漢字と English の間に空白を置く文書では、改行も English の前で空白になります。
+
+漢字とEnglishの間に空白を置かない文書では、改行はEnglishの前でも消えます。
+
+한국어는 라틴 문자처럼 띄어쓰기로 단어를 나눕니다.
+
+営業時間は月〜金の9時〜18時です。詳しくは……後日お知らせします……
+
+括弧の前 (paren) と後ろ、ASCII 記号の :: 前後は空白になります。
+
+---------------------------------------
+{ printWidth: 100, proseWrap: "never" }
+---------------------------------------
+<!-- Whitespace around Chinese / Japanese: a line break between CJ characters is nothing,
+     a space next to CJ text never breaks, Korean behaves like Latin -->
+
+日本語の文章は改行しても空白になりません。
+
+漢字と English の間に空白を置く文書では、改行も English の前で空白になります。
+
+漢字とEnglishの間に空白を置かない文書では、改行はEnglishの前でも消えます。
+
+한국어는 라틴 문자처럼 띄어쓰기로 단어를 나눕니다.
+
+営業時間は月〜金の9時〜18時です。詳しくは……後日お知らせします……
+
+括弧の前 (paren) と後ろ、ASCII 記号の :: 前後は空白になります。
+
+-----------------------------------------
+{ printWidth: 80, proseWrap: "preserve" }
+-----------------------------------------
+<!-- Whitespace around Chinese / Japanese: a line break between CJ characters is nothing,
+     a space next to CJ text never breaks, Korean behaves like Latin -->
+
+日本語の文章は
+改行しても
+空白になりません。
+
+漢字と English の間に空白を置く文書では、改行も
+English の前で空白になります。
+
+漢字とEnglishの間に空白を置かない文書では、改行は
+Englishの前でも消えます。
+
+한국어는 라틴 문자처럼
+띄어쓰기로 단어를 나눕니다.
+
+営業時間は月〜
+金の9時〜
+18時です。詳しくは……
+後日お知らせします……
+
+括弧の前 (paren) と後ろ、ASCII 記号の
+:: 前後は空白になります。
+
+------------------------------------------
+{ printWidth: 100, proseWrap: "preserve" }
+------------------------------------------
+<!-- Whitespace around Chinese / Japanese: a line break between CJ characters is nothing,
+     a space next to CJ text never breaks, Korean behaves like Latin -->
+
+日本語の文章は
+改行しても
+空白になりません。
+
+漢字と English の間に空白を置く文書では、改行も
+English の前で空白になります。
+
+漢字とEnglishの間に空白を置かない文書では、改行は
+Englishの前でも消えます。
+
+한국어는 라틴 문자처럼
+띄어쓰기로 단어를 나눕니다.
+
+営業時間は月〜
+金の9時〜
+18時です。詳しくは……
+後日お知らせします……
+
+括弧の前 (paren) と後ろ、ASCII 記号の
+:: 前後は空白になります。
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/container-directive.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/container-directive.md
new file mode 100644
index 0000000000..920d8a7da2
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/container-directive.md
@@ -0,0 +1,21 @@
+<!-- `:::` fence lines are kept as written; only the children are formatted.
+     The opener takes any name-like line: remark `:::name[label]{attrs}`, VitePress `::: tip Title`, Pandoc `::: {.class}`.
+     Nesting goes outer-longer, as in remark-directive: a fence of 3+ `:` alone closes the outermost open directive it fits -->
+
+::::warning
+Some **text** that is
+long enough to wrap when the width is small and prose wrap is always on.
+
+:::nested
+inner
+:::
+::::
+
+::: tip Custom Title
+Some **text** that is
+long enough to wrap when the width is small and prose wrap is always on.
+:::
+
+::: {.class}
+Pandoc fenced div.
+:::
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/container-directive.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/container-directive.md.snap
new file mode 100644
index 0000000000..6aa4d67e7c
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/container-directive.md.snap
@@ -0,0 +1,172 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- `:::` fence lines are kept as written; only the children are formatted.
+     The opener takes any name-like line: remark `:::name[label]{attrs}`, VitePress `::: tip Title`, Pandoc `::: {.class}`.
+     Nesting goes outer-longer, as in remark-directive: a fence of 3+ `:` alone closes the outermost open directive it fits -->
+
+::::warning
+Some **text** that is
+long enough to wrap when the width is small and prose wrap is always on.
+
+:::nested
+inner
+:::
+::::
+
+::: tip Custom Title
+Some **text** that is
+long enough to wrap when the width is small and prose wrap is always on.
+:::
+
+::: {.class}
+Pandoc fenced div.
+:::
+
+==================== Output ====================
+---------------------------------------
+{ printWidth: 80, proseWrap: "always" }
+---------------------------------------
+<!-- `:::` fence lines are kept as written; only the children are formatted.
+     The opener takes any name-like line: remark `:::name[label]{attrs}`, VitePress `::: tip Title`, Pandoc `::: {.class}`.
+     Nesting goes outer-longer, as in remark-directive: a fence of 3+ `:` alone closes the outermost open directive it fits -->
+
+::::warning
+Some **text** that is long enough to wrap when the width is small and prose wrap
+is always on.
+
+:::nested
+inner
+:::
+::::
+
+::: tip Custom Title
+Some **text** that is long enough to wrap when the width is small and prose wrap
+is always on.
+:::
+
+::: {.class}
+Pandoc fenced div.
+:::
+
+----------------------------------------
+{ printWidth: 100, proseWrap: "always" }
+----------------------------------------
+<!-- `:::` fence lines are kept as written; only the children are formatted.
+     The opener takes any name-like line: remark `:::name[label]{attrs}`, VitePress `::: tip Title`, Pandoc `::: {.class}`.
+     Nesting goes outer-longer, as in remark-directive: a fence of 3+ `:` alone closes the outermost open directive it fits -->
+
+::::warning
+Some **text** that is long enough to wrap when the width is small and prose wrap is always on.
+
+:::nested
+inner
+:::
+::::
+
+::: tip Custom Title
+Some **text** that is long enough to wrap when the width is small and prose wrap is always on.
+:::
+
+::: {.class}
+Pandoc fenced div.
+:::
+
+--------------------------------------
+{ printWidth: 80, proseWrap: "never" }
+--------------------------------------
+<!-- `:::` fence lines are kept as written; only the children are formatted.
+     The opener takes any name-like line: remark `:::name[label]{attrs}`, VitePress `::: tip Title`, Pandoc `::: {.class}`.
+     Nesting goes outer-longer, as in remark-directive: a fence of 3+ `:` alone closes the outermost open directive it fits -->
+
+::::warning
+Some **text** that is long enough to wrap when the width is small and prose wrap is always on.
+
+:::nested
+inner
+:::
+::::
+
+::: tip Custom Title
+Some **text** that is long enough to wrap when the width is small and prose wrap is always on.
+:::
+
+::: {.class}
+Pandoc fenced div.
+:::
+
+---------------------------------------
+{ printWidth: 100, proseWrap: "never" }
+---------------------------------------
+<!-- `:::` fence lines are kept as written; only the children are formatted.
+     The opener takes any name-like line: remark `:::name[label]{attrs}`, VitePress `::: tip Title`, Pandoc `::: {.class}`.
+     Nesting goes outer-longer, as in remark-directive: a fence of 3+ `:` alone closes the outermost open directive it fits -->
+
+::::warning
+Some **text** that is long enough to wrap when the width is small and prose wrap is always on.
+
+:::nested
+inner
+:::
+::::
+
+::: tip Custom Title
+Some **text** that is long enough to wrap when the width is small and prose wrap is always on.
+:::
+
+::: {.class}
+Pandoc fenced div.
+:::
+
+-----------------------------------------
+{ printWidth: 80, proseWrap: "preserve" }
+-----------------------------------------
+<!-- `:::` fence lines are kept as written; only the children are formatted.
+     The opener takes any name-like line: remark `:::name[label]{attrs}`, VitePress `::: tip Title`, Pandoc `::: {.class}`.
+     Nesting goes outer-longer, as in remark-directive: a fence of 3+ `:` alone closes the outermost open directive it fits -->
+
+::::warning
+Some **text** that is
+long enough to wrap when the width is small and prose wrap is always on.
+
+:::nested
+inner
+:::
+::::
+
+::: tip Custom Title
+Some **text** that is
+long enough to wrap when the width is small and prose wrap is always on.
+:::
+
+::: {.class}
+Pandoc fenced div.
+:::
+
+------------------------------------------
+{ printWidth: 100, proseWrap: "preserve" }
+------------------------------------------
+<!-- `:::` fence lines are kept as written; only the children are formatted.
+     The opener takes any name-like line: remark `:::name[label]{attrs}`, VitePress `::: tip Title`, Pandoc `::: {.class}`.
+     Nesting goes outer-longer, as in remark-directive: a fence of 3+ `:` alone closes the outermost open directive it fits -->
+
+::::warning
+Some **text** that is
+long enough to wrap when the width is small and prose wrap is always on.
+
+:::nested
+inner
+:::
+::::
+
+::: tip Custom Title
+Some **text** that is
+long enough to wrap when the width is small and prose wrap is always on.
+:::
+
+::: {.class}
+Pandoc fenced div.
+:::
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/ignored-block-trailing-quote-line.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/ignored-block-trailing-quote-line.md
new file mode 100644
index 0000000000..aeddd31d32
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/ignored-block-trailing-quote-line.md
@@ -0,0 +1,8 @@
+<!-- The blank `> ` line after the ignored list is dropped under every proseWrap;
+     Prettier prints it as `>` under `always` only -->
+
+> <!-- prettier-ignore -->
+> - a   long   item
+> 
+
+> next
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/ignored-block-trailing-quote-line.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/ignored-block-trailing-quote-line.md.snap
new file mode 100644
index 0000000000..99cfba4c6f
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/ignored-block-trailing-quote-line.md.snap
@@ -0,0 +1,81 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- The blank `> ` line after the ignored list is dropped under every proseWrap;
+     Prettier prints it as `>` under `always` only -->
+
+> <!-- prettier-ignore -->
+> - a   long   item
+> 
+
+> next
+
+==================== Output ====================
+---------------------------------------
+{ printWidth: 80, proseWrap: "always" }
+---------------------------------------
+<!-- The blank `> ` line after the ignored list is dropped under every proseWrap;
+     Prettier prints it as `>` under `always` only -->
+
+> <!-- prettier-ignore -->
+> - a   long   item
+
+> next
+
+----------------------------------------
+{ printWidth: 100, proseWrap: "always" }
+----------------------------------------
+<!-- The blank `> ` line after the ignored list is dropped under every proseWrap;
+     Prettier prints it as `>` under `always` only -->
+
+> <!-- prettier-ignore -->
+> - a   long   item
+
+> next
+
+--------------------------------------
+{ printWidth: 80, proseWrap: "never" }
+--------------------------------------
+<!-- The blank `> ` line after the ignored list is dropped under every proseWrap;
+     Prettier prints it as `>` under `always` only -->
+
+> <!-- prettier-ignore -->
+> - a   long   item
+
+> next
+
+---------------------------------------
+{ printWidth: 100, proseWrap: "never" }
+---------------------------------------
+<!-- The blank `> ` line after the ignored list is dropped under every proseWrap;
+     Prettier prints it as `>` under `always` only -->
+
+> <!-- prettier-ignore -->
+> - a   long   item
+
+> next
+
+-----------------------------------------
+{ printWidth: 80, proseWrap: "preserve" }
+-----------------------------------------
+<!-- The blank `> ` line after the ignored list is dropped under every proseWrap;
+     Prettier prints it as `>` under `always` only -->
+
+> <!-- prettier-ignore -->
+> - a   long   item
+
+> next
+
+------------------------------------------
+{ printWidth: 100, proseWrap: "preserve" }
+------------------------------------------
+<!-- The blank `> ` line after the ignored list is dropped under every proseWrap;
+     Prettier prints it as `>` under `always` only -->
+
+> <!-- prettier-ignore -->
+> - a   long   item
+
+> next
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/line-shapes.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/line-shapes.md
new file mode 100644
index 0000000000..2bac486977
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/line-shapes.md
@@ -0,0 +1,20 @@
+<!-- Dialect line shapes keep their line boundaries and are never re-wrapped:
+     `<<<` snippet imports, component tags, `[!TYPE]` alert markers, stray `:::` lines -->
+
+Intro text before a snippet import that is long enough to wrap when prose wrap is always.
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
+<<< @/snippets/other.js
+Text after the imports that is long enough to wrap when prose wrap is always on.
+
+> [!TIP] Custom title
+> Body of the alert, long enough to wrap when prose wrap is always and the width is small.
+
+> [!NOTE]
+> `DOOM`
+
+Click <Badge type="tip" text="new" /> to see it, a sentence long enough to wrap around the tag.
+<Badge type="tip" text="new" />
+<my-element some-attribute="value">inline</my-element>
+<span>plain html</span> keeps wrapping with the prose around it as usual.
+:::)
+plain text after an emoticon line that is long enough to wrap when prose wrap is always on.
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/line-shapes.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/line-shapes.md.snap
new file mode 100644
index 0000000000..c3d2853e50
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/line-shapes.md.snap
@@ -0,0 +1,175 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- Dialect line shapes keep their line boundaries and are never re-wrapped:
+     `<<<` snippet imports, component tags, `[!TYPE]` alert markers, stray `:::` lines -->
+
+Intro text before a snippet import that is long enough to wrap when prose wrap is always.
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
+<<< @/snippets/other.js
+Text after the imports that is long enough to wrap when prose wrap is always on.
+
+> [!TIP] Custom title
+> Body of the alert, long enough to wrap when prose wrap is always and the width is small.
+
+> [!NOTE]
+> `DOOM`
+
+Click <Badge type="tip" text="new" /> to see it, a sentence long enough to wrap around the tag.
+<Badge type="tip" text="new" />
+<my-element some-attribute="value">inline</my-element>
+<span>plain html</span> keeps wrapping with the prose around it as usual.
+:::)
+plain text after an emoticon line that is long enough to wrap when prose wrap is always on.
+
+==================== Output ====================
+---------------------------------------
+{ printWidth: 80, proseWrap: "always" }
+---------------------------------------
+<!-- Dialect line shapes keep their line boundaries and are never re-wrapped:
+     `<<<` snippet imports, component tags, `[!TYPE]` alert markers, stray `:::` lines -->
+
+Intro text before a snippet import that is long enough to wrap when prose wrap
+is always.
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
+<<< @/snippets/other.js
+Text after the imports that is long enough to wrap when prose wrap is always on.
+
+> [!TIP] Custom title
+> Body of the alert, long enough to wrap when prose wrap is always and the width
+> is small.
+
+> [!NOTE]
+> `DOOM`
+
+Click <Badge type="tip" text="new" /> to see it, a sentence long enough to wrap
+around the tag.
+<Badge type="tip" text="new" />
+<my-element some-attribute="value">inline</my-element>
+<span>plain html</span> keeps wrapping with the prose around it as usual.
+:::)
+plain text after an emoticon line that is long enough to wrap when prose wrap is
+always on.
+
+----------------------------------------
+{ printWidth: 100, proseWrap: "always" }
+----------------------------------------
+<!-- Dialect line shapes keep their line boundaries and are never re-wrapped:
+     `<<<` snippet imports, component tags, `[!TYPE]` alert markers, stray `:::` lines -->
+
+Intro text before a snippet import that is long enough to wrap when prose wrap is always.
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
+<<< @/snippets/other.js
+Text after the imports that is long enough to wrap when prose wrap is always on.
+
+> [!TIP] Custom title
+> Body of the alert, long enough to wrap when prose wrap is always and the width is small.
+
+> [!NOTE]
+> `DOOM`
+
+Click <Badge type="tip" text="new" /> to see it, a sentence long enough to wrap around the tag.
+<Badge type="tip" text="new" />
+<my-element some-attribute="value">inline</my-element>
+<span>plain html</span> keeps wrapping with the prose around it as usual.
+:::)
+plain text after an emoticon line that is long enough to wrap when prose wrap is always on.
+
+--------------------------------------
+{ printWidth: 80, proseWrap: "never" }
+--------------------------------------
+<!-- Dialect line shapes keep their line boundaries and are never re-wrapped:
+     `<<<` snippet imports, component tags, `[!TYPE]` alert markers, stray `:::` lines -->
+
+Intro text before a snippet import that is long enough to wrap when prose wrap is always.
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
+<<< @/snippets/other.js
+Text after the imports that is long enough to wrap when prose wrap is always on.
+
+> [!TIP] Custom title
+> Body of the alert, long enough to wrap when prose wrap is always and the width is small.
+
+> [!NOTE]
+> `DOOM`
+
+Click <Badge type="tip" text="new" /> to see it, a sentence long enough to wrap around the tag.
+<Badge type="tip" text="new" />
+<my-element some-attribute="value">inline</my-element>
+<span>plain html</span> keeps wrapping with the prose around it as usual.
+:::)
+plain text after an emoticon line that is long enough to wrap when prose wrap is always on.
+
+---------------------------------------
+{ printWidth: 100, proseWrap: "never" }
+---------------------------------------
+<!-- Dialect line shapes keep their line boundaries and are never re-wrapped:
+     `<<<` snippet imports, component tags, `[!TYPE]` alert markers, stray `:::` lines -->
+
+Intro text before a snippet import that is long enough to wrap when prose wrap is always.
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
+<<< @/snippets/other.js
+Text after the imports that is long enough to wrap when prose wrap is always on.
+
+> [!TIP] Custom title
+> Body of the alert, long enough to wrap when prose wrap is always and the width is small.
+
+> [!NOTE]
+> `DOOM`
+
+Click <Badge type="tip" text="new" /> to see it, a sentence long enough to wrap around the tag.
+<Badge type="tip" text="new" />
+<my-element some-attribute="value">inline</my-element>
+<span>plain html</span> keeps wrapping with the prose around it as usual.
+:::)
+plain text after an emoticon line that is long enough to wrap when prose wrap is always on.
+
+-----------------------------------------
+{ printWidth: 80, proseWrap: "preserve" }
+-----------------------------------------
+<!-- Dialect line shapes keep their line boundaries and are never re-wrapped:
+     `<<<` snippet imports, component tags, `[!TYPE]` alert markers, stray `:::` lines -->
+
+Intro text before a snippet import that is long enough to wrap when prose wrap is always.
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
+<<< @/snippets/other.js
+Text after the imports that is long enough to wrap when prose wrap is always on.
+
+> [!TIP] Custom title
+> Body of the alert, long enough to wrap when prose wrap is always and the width is small.
+
+> [!NOTE]
+> `DOOM`
+
+Click <Badge type="tip" text="new" /> to see it, a sentence long enough to wrap around the tag.
+<Badge type="tip" text="new" />
+<my-element some-attribute="value">inline</my-element>
+<span>plain html</span> keeps wrapping with the prose around it as usual.
+:::)
+plain text after an emoticon line that is long enough to wrap when prose wrap is always on.
+
+------------------------------------------
+{ printWidth: 100, proseWrap: "preserve" }
+------------------------------------------
+<!-- Dialect line shapes keep their line boundaries and are never re-wrapped:
+     `<<<` snippet imports, component tags, `[!TYPE]` alert markers, stray `:::` lines -->
+
+Intro text before a snippet import that is long enough to wrap when prose wrap is always.
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
+<<< @/snippets/other.js
+Text after the imports that is long enough to wrap when prose wrap is always on.
+
+> [!TIP] Custom title
+> Body of the alert, long enough to wrap when prose wrap is always and the width is small.
+
+> [!NOTE]
+> `DOOM`
+
+Click <Badge type="tip" text="new" /> to see it, a sentence long enough to wrap around the tag.
+<Badge type="tip" text="new" />
+<my-element some-attribute="value">inline</my-element>
+<span>plain html</span> keeps wrapping with the prose around it as usual.
+:::)
+plain text after an emoticon line that is long enough to wrap when prose wrap is always on.
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/liquid-flow.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/liquid-flow.md
new file mode 100644
index 0000000000..557d699e4f
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/liquid-flow.md
@@ -0,0 +1,11 @@
+<!-- Flow liquid tags: two tags on adjacent lines stay on their lines,
+     blank lines and inner whitespace inside a tag are kept -->
+
+{% css userscripts %}
+{% js userscripts %}
+
+{{ foo
+
+bar   baz
+
+qux }}
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/liquid-flow.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/liquid-flow.md.snap
new file mode 100644
index 0000000000..91b5282565
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/liquid-flow.md.snap
@@ -0,0 +1,108 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- Flow liquid tags: two tags on adjacent lines stay on their lines,
+     blank lines and inner whitespace inside a tag are kept -->
+
+{% css userscripts %}
+{% js userscripts %}
+
+{{ foo
+
+bar   baz
+
+qux }}
+
+==================== Output ====================
+---------------------------------------
+{ printWidth: 80, proseWrap: "always" }
+---------------------------------------
+<!-- Flow liquid tags: two tags on adjacent lines stay on their lines,
+     blank lines and inner whitespace inside a tag are kept -->
+
+{% css userscripts %}
+{% js userscripts %}
+
+{{ foo
+
+bar   baz
+
+qux }}
+
+----------------------------------------
+{ printWidth: 100, proseWrap: "always" }
+----------------------------------------
+<!-- Flow liquid tags: two tags on adjacent lines stay on their lines,
+     blank lines and inner whitespace inside a tag are kept -->
+
+{% css userscripts %}
+{% js userscripts %}
+
+{{ foo
+
+bar   baz
+
+qux }}
+
+--------------------------------------
+{ printWidth: 80, proseWrap: "never" }
+--------------------------------------
+<!-- Flow liquid tags: two tags on adjacent lines stay on their lines,
+     blank lines and inner whitespace inside a tag are kept -->
+
+{% css userscripts %}
+{% js userscripts %}
+
+{{ foo
+
+bar   baz
+
+qux }}
+
+---------------------------------------
+{ printWidth: 100, proseWrap: "never" }
+---------------------------------------
+<!-- Flow liquid tags: two tags on adjacent lines stay on their lines,
+     blank lines and inner whitespace inside a tag are kept -->
+
+{% css userscripts %}
+{% js userscripts %}
+
+{{ foo
+
+bar   baz
+
+qux }}
+
+-----------------------------------------
+{ printWidth: 80, proseWrap: "preserve" }
+-----------------------------------------
+<!-- Flow liquid tags: two tags on adjacent lines stay on their lines,
+     blank lines and inner whitespace inside a tag are kept -->
+
+{% css userscripts %}
+{% js userscripts %}
+
+{{ foo
+
+bar   baz
+
+qux }}
+
+------------------------------------------
+{ printWidth: 100, proseWrap: "preserve" }
+------------------------------------------
+<!-- Flow liquid tags: two tags on adjacent lines stay on their lines,
+     blank lines and inner whitespace inside a tag are kept -->
+
+{% css userscripts %}
+{% js userscripts %}
+
+{{ foo
+
+bar   baz
+
+qux }}
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/options.json b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/options.json
new file mode 100644
index 0000000000..6a3b17ca8f
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/options.json
@@ -0,0 +1 @@
+[{ "proseWrap": "always" }, { "proseWrap": "never" }, { "proseWrap": "preserve" }]
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/stray-delimiters.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/stray-delimiters.md
new file mode 100644
index 0000000000..12e69a7993
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/stray-delimiters.md
@@ -0,0 +1,24 @@
+<!-- A code span fence never equals a literal backtick run before it.
+     Emphasis markers normalize only when the printed text pairs as the source did;
+     otherwise they stay as written -->
+
+A stray ` backtick and then ``code`` that must not shrink to one backtick.
+
+A literal *** run and then __strong__ that may become two asterisks (still one strong).
+
+A literal _ underscore and then *emphasis* that may become underscores (still one emphasis).
+
+No stray run here, so ``code`` shrinks and __strong__ and *emphasis* normalize.
+
+**a ***b*** c** keeps its asterisks: with `_` the inner emphasis reads differently.
+
+*a**b* keeps its inner run escaped, and _a\_\_b_ its normalized marker.
+
+A backslash \ before a line break stays on its line, never a hard break \
+when the next word arrives.
+
+[label]: /destination followed by text that is not a title keeps its first line
+whole (a wrap after the destination would leave a definition behind).
+
+text\
+	:::note after a hard break was indented in the source and stays paragraph text
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/stray-delimiters.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/stray-delimiters.md.snap
new file mode 100644
index 0000000000..fa552a0d62
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/stray-delimiters.md.snap
@@ -0,0 +1,203 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- A code span fence never equals a literal backtick run before it.
+     Emphasis markers normalize only when the printed text pairs as the source did;
+     otherwise they stay as written -->
+
+A stray ` backtick and then ``code`` that must not shrink to one backtick.
+
+A literal *** run and then __strong__ that may become two asterisks (still one strong).
+
+A literal _ underscore and then *emphasis* that may become underscores (still one emphasis).
+
+No stray run here, so ``code`` shrinks and __strong__ and *emphasis* normalize.
+
+**a ***b*** c** keeps its asterisks: with `_` the inner emphasis reads differently.
+
+*a**b* keeps its inner run escaped, and _a\_\_b_ its normalized marker.
+
+A backslash \ before a line break stays on its line, never a hard break \
+when the next word arrives.
+
+[label]: /destination followed by text that is not a title keeps its first line
+whole (a wrap after the destination would leave a definition behind).
+
+text\
+	:::note after a hard break was indented in the source and stays paragraph text
+
+==================== Output ====================
+---------------------------------------
+{ printWidth: 80, proseWrap: "always" }
+---------------------------------------
+<!-- A code span fence never equals a literal backtick run before it.
+     Emphasis markers normalize only when the printed text pairs as the source did;
+     otherwise they stay as written -->
+
+A stray ` backtick and then ``code`` that must not shrink to one backtick.
+
+A literal *** run and then **strong** that may become two asterisks (still one
+strong).
+
+A literal _ underscore and then _emphasis_ that may become underscores (still
+one emphasis).
+
+No stray run here, so `code` shrinks and **strong** and _emphasis_ normalize.
+
+**a ***b*** c** keeps its asterisks: with `_` the inner emphasis reads
+differently.
+
+_a\*\*b_ keeps its inner run escaped, and _a\_\_b_ its normalized marker.
+
+A backslash \ before a line break stays on its line, never a hard break \
+when the next word arrives.
+
+[label]: /destination followed by text that is not a title keeps its first line
+whole (a wrap after the destination would leave a definition behind).
+
+text\
+    :::note after a hard break was indented in the source and stays paragraph
+text
+
+----------------------------------------
+{ printWidth: 100, proseWrap: "always" }
+----------------------------------------
+<!-- A code span fence never equals a literal backtick run before it.
+     Emphasis markers normalize only when the printed text pairs as the source did;
+     otherwise they stay as written -->
+
+A stray ` backtick and then ``code`` that must not shrink to one backtick.
+
+A literal *** run and then **strong** that may become two asterisks (still one strong).
+
+A literal _ underscore and then _emphasis_ that may become underscores (still one emphasis).
+
+No stray run here, so `code` shrinks and **strong** and _emphasis_ normalize.
+
+**a ***b*** c** keeps its asterisks: with `_` the inner emphasis reads differently.
+
+_a\*\*b_ keeps its inner run escaped, and _a\_\_b_ its normalized marker.
+
+A backslash \ before a line break stays on its line, never a hard break \
+when the next word arrives.
+
+[label]: /destination followed by text that is not a title keeps its first line
+whole (a wrap after the destination would leave a definition behind).
+
+text\
+    :::note after a hard break was indented in the source and stays paragraph text
+
+--------------------------------------
+{ printWidth: 80, proseWrap: "never" }
+--------------------------------------
+<!-- A code span fence never equals a literal backtick run before it.
+     Emphasis markers normalize only when the printed text pairs as the source did;
+     otherwise they stay as written -->
+
+A stray ` backtick and then ``code`` that must not shrink to one backtick.
+
+A literal *** run and then **strong** that may become two asterisks (still one strong).
+
+A literal _ underscore and then _emphasis_ that may become underscores (still one emphasis).
+
+No stray run here, so `code` shrinks and **strong** and _emphasis_ normalize.
+
+**a ***b*** c** keeps its asterisks: with `_` the inner emphasis reads differently.
+
+_a\*\*b_ keeps its inner run escaped, and _a\_\_b_ its normalized marker.
+
+A backslash \ before a line break stays on its line, never a hard break \
+when the next word arrives.
+
+[label]: /destination followed by text that is not a title keeps its first line
+whole (a wrap after the destination would leave a definition behind).
+
+text\
+    :::note after a hard break was indented in the source and stays paragraph text
+
+---------------------------------------
+{ printWidth: 100, proseWrap: "never" }
+---------------------------------------
+<!-- A code span fence never equals a literal backtick run before it.
+     Emphasis markers normalize only when the printed text pairs as the source did;
+     otherwise they stay as written -->
+
+A stray ` backtick and then ``code`` that must not shrink to one backtick.
+
+A literal *** run and then **strong** that may become two asterisks (still one strong).
+
+A literal _ underscore and then _emphasis_ that may become underscores (still one emphasis).
+
+No stray run here, so `code` shrinks and **strong** and _emphasis_ normalize.
+
+**a ***b*** c** keeps its asterisks: with `_` the inner emphasis reads differently.
+
+_a\*\*b_ keeps its inner run escaped, and _a\_\_b_ its normalized marker.
+
+A backslash \ before a line break stays on its line, never a hard break \
+when the next word arrives.
+
+[label]: /destination followed by text that is not a title keeps its first line
+whole (a wrap after the destination would leave a definition behind).
+
+text\
+    :::note after a hard break was indented in the source and stays paragraph text
+
+-----------------------------------------
+{ printWidth: 80, proseWrap: "preserve" }
+-----------------------------------------
+<!-- A code span fence never equals a literal backtick run before it.
+     Emphasis markers normalize only when the printed text pairs as the source did;
+     otherwise they stay as written -->
+
+A stray ` backtick and then ``code`` that must not shrink to one backtick.
+
+A literal *** run and then **strong** that may become two asterisks (still one strong).
+
+A literal _ underscore and then _emphasis_ that may become underscores (still one emphasis).
+
+No stray run here, so `code` shrinks and **strong** and _emphasis_ normalize.
+
+**a ***b*** c** keeps its asterisks: with `_` the inner emphasis reads differently.
+
+_a\*\*b_ keeps its inner run escaped, and _a\_\_b_ its normalized marker.
+
+A backslash \ before a line break stays on its line, never a hard break \
+when the next word arrives.
+
+[label]: /destination followed by text that is not a title keeps its first line
+whole (a wrap after the destination would leave a definition behind).
+
+text\
+    :::note after a hard break was indented in the source and stays paragraph text
+
+------------------------------------------
+{ printWidth: 100, proseWrap: "preserve" }
+------------------------------------------
+<!-- A code span fence never equals a literal backtick run before it.
+     Emphasis markers normalize only when the printed text pairs as the source did;
+     otherwise they stay as written -->
+
+A stray ` backtick and then ``code`` that must not shrink to one backtick.
+
+A literal *** run and then **strong** that may become two asterisks (still one strong).
+
+A literal _ underscore and then _emphasis_ that may become underscores (still one emphasis).
+
+No stray run here, so `code` shrinks and **strong** and _emphasis_ normalize.
+
+**a ***b*** c** keeps its asterisks: with `_` the inner emphasis reads differently.
+
+_a\*\*b_ keeps its inner run escaped, and _a\_\_b_ its normalized marker.
+
+A backslash \ before a line break stays on its line, never a hard break \
+when the next word arrives.
+
+[label]: /destination followed by text that is not a title keeps its first line
+whole (a wrap after the destination would leave a definition behind).
+
+text\
+    :::note after a hard break was indented in the source and stays paragraph text
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wiki-link-code-span.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wiki-link-code-span.md
new file mode 100644
index 0000000000..25fdf1b15c
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wiki-link-code-span.md
@@ -0,0 +1,4 @@
+<!-- A `[[` ... `]]` paragraph is printed as written; a code span inside keeps its line break too -->
+
+See [[the `first
+second` note]] for details.
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wiki-link-code-span.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wiki-link-code-span.md.snap
new file mode 100644
index 0000000000..6e061caa15
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wiki-link-code-span.md.snap
@@ -0,0 +1,59 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- A `[[` ... `]]` paragraph is printed as written; a code span inside keeps its line break too -->
+
+See [[the `first
+second` note]] for details.
+
+==================== Output ====================
+---------------------------------------
+{ printWidth: 80, proseWrap: "always" }
+---------------------------------------
+<!-- A `[[` ... `]]` paragraph is printed as written; a code span inside keeps its line break too -->
+
+See [[the `first
+second` note]] for details.
+
+----------------------------------------
+{ printWidth: 100, proseWrap: "always" }
+----------------------------------------
+<!-- A `[[` ... `]]` paragraph is printed as written; a code span inside keeps its line break too -->
+
+See [[the `first
+second` note]] for details.
+
+--------------------------------------
+{ printWidth: 80, proseWrap: "never" }
+--------------------------------------
+<!-- A `[[` ... `]]` paragraph is printed as written; a code span inside keeps its line break too -->
+
+See [[the `first
+second` note]] for details.
+
+---------------------------------------
+{ printWidth: 100, proseWrap: "never" }
+---------------------------------------
+<!-- A `[[` ... `]]` paragraph is printed as written; a code span inside keeps its line break too -->
+
+See [[the `first
+second` note]] for details.
+
+-----------------------------------------
+{ printWidth: 80, proseWrap: "preserve" }
+-----------------------------------------
+<!-- A `[[` ... `]]` paragraph is printed as written; a code span inside keeps its line break too -->
+
+See [[the `first
+second` note]] for details.
+
+------------------------------------------
+{ printWidth: 100, proseWrap: "preserve" }
+------------------------------------------
+<!-- A `[[` ... `]]` paragraph is printed as written; a code span inside keeps its line break too -->
+
+See [[the `first
+second` note]] for details.
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wrap-block-starts.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wrap-block-starts.md
new file mode 100644
index 0000000000..ecde1dcaab
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wrap-block-starts.md
@@ -0,0 +1,32 @@
+<!-- A word that would open a block at a line start never begins a wrapped line:
+     the parser's `lexical::line_start` decides, not a list of markers -->
+
+padding words to push the risky token over the edge padding words to push <!-- c --> tail words.
+
+padding words to push the risky token over the edge padding words to <div>x</div> tail words.
+
+padding words to push the risky token over the edge padding words to push the *** tail words.
+
+padding words to push the risky token over the edge padding words to push the --- tail words.
+
+padding words to push the risky token over the edge padding words to push the 1. tail words.
+
+padding words to push the risky token over the edge padding words to push the ``` tail words.
+
+padding words to push the risky token over the edge padding words to push the | a | tail words.
+
+padding words to push the risky token over the edge padding words to push [^1]: tail words.
+
+padding words to push the risky token over the edge padding words to push the - item tail words.
+
+padding words to push the risky token over the edge padding words to push the # not a heading tail words.
+
+padding words to push the risky token over the edge padding words to push the > not a quote tail words.
+
+<!-- A kept line break whose next line loses its indentation is dropped the same way: printed at the line start, the row would be a table delimiter -->
+
+| x | y |
+        |---|---|
+
+text then
+    - item
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wrap-block-starts.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wrap-block-starts.md.snap
new file mode 100644
index 0000000000..9a0e17762f
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/prose-wrap/wrap-block-starts.md.snap
@@ -0,0 +1,256 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- A word that would open a block at a line start never begins a wrapped line:
+     the parser's `lexical::line_start` decides, not a list of markers -->
+
+padding words to push the risky token over the edge padding words to push <!-- c --> tail words.
+
+padding words to push the risky token over the edge padding words to <div>x</div> tail words.
+
+padding words to push the risky token over the edge padding words to push the *** tail words.
+
+padding words to push the risky token over the edge padding words to push the --- tail words.
+
+padding words to push the risky token over the edge padding words to push the 1. tail words.
+
+padding words to push the risky token over the edge padding words to push the ``` tail words.
+
+padding words to push the risky token over the edge padding words to push the | a | tail words.
+
+padding words to push the risky token over the edge padding words to push [^1]: tail words.
+
+padding words to push the risky token over the edge padding words to push the - item tail words.
+
+padding words to push the risky token over the edge padding words to push the # not a heading tail words.
+
+padding words to push the risky token over the edge padding words to push the > not a quote tail words.
+
+<!-- A kept line break whose next line loses its indentation is dropped the same way: printed at the line start, the row would be a table delimiter -->
+
+| x | y |
+        |---|---|
+
+text then
+    - item
+
+==================== Output ====================
+---------------------------------------
+{ printWidth: 80, proseWrap: "always" }
+---------------------------------------
+<!-- A word that would open a block at a line start never begins a wrapped line:
+     the parser's `lexical::line_start` decides, not a list of markers -->
+
+padding words to push the risky token over the edge padding words to
+push <!-- c --> tail words.
+
+padding words to push the risky token over the edge padding words
+to <div>x</div> tail words.
+
+padding words to push the risky token over the edge padding words to push
+the *** tail words.
+
+padding words to push the risky token over the edge padding words to push
+the --- tail words.
+
+padding words to push the risky token over the edge padding words to push the 1.
+tail words.
+
+padding words to push the risky token over the edge padding words to push
+the ``` tail words.
+
+padding words to push the risky token over the edge padding words to push the |
+a | tail words.
+
+padding words to push the risky token over the edge padding words to push [^1]:
+tail words.
+
+padding words to push the risky token over the edge padding words to push the -
+item tail words.
+
+padding words to push the risky token over the edge padding words to push the #
+not a heading tail words.
+
+padding words to push the risky token over the edge padding words to push the >
+not a quote tail words.
+
+<!-- A kept line break whose next line loses its indentation is dropped the same way: printed at the line start, the row would be a table delimiter -->
+
+| x | y | |---|---|
+
+text then - item
+
+----------------------------------------
+{ printWidth: 100, proseWrap: "always" }
+----------------------------------------
+<!-- A word that would open a block at a line start never begins a wrapped line:
+     the parser's `lexical::line_start` decides, not a list of markers -->
+
+padding words to push the risky token over the edge padding words to push <!-- c --> tail words.
+
+padding words to push the risky token over the edge padding words to <div>x</div> tail words.
+
+padding words to push the risky token over the edge padding words to push the *** tail words.
+
+padding words to push the risky token over the edge padding words to push the --- tail words.
+
+padding words to push the risky token over the edge padding words to push the 1. tail words.
+
+padding words to push the risky token over the edge padding words to push the ``` tail words.
+
+padding words to push the risky token over the edge padding words to push the | a | tail words.
+
+padding words to push the risky token over the edge padding words to push [^1]: tail words.
+
+padding words to push the risky token over the edge padding words to push the - item tail words.
+
+padding words to push the risky token over the edge padding words to push the # not a heading tail
+words.
+
+padding words to push the risky token over the edge padding words to push the > not a quote tail
+words.
+
+<!-- A kept line break whose next line loses its indentation is dropped the same way: printed at the line start, the row would be a table delimiter -->
+
+| x | y | |---|---|
+
+text then - item
+
+--------------------------------------
+{ printWidth: 80, proseWrap: "never" }
+--------------------------------------
+<!-- A word that would open a block at a line start never begins a wrapped line:
+     the parser's `lexical::line_start` decides, not a list of markers -->
+
+padding words to push the risky token over the edge padding words to push <!-- c --> tail words.
+
+padding words to push the risky token over the edge padding words to <div>x</div> tail words.
+
+padding words to push the risky token over the edge padding words to push the *** tail words.
+
+padding words to push the risky token over the edge padding words to push the --- tail words.
+
+padding words to push the risky token over the edge padding words to push the 1. tail words.
+
+padding words to push the risky token over the edge padding words to push the ``` tail words.
+
+padding words to push the risky token over the edge padding words to push the | a | tail words.
+
+padding words to push the risky token over the edge padding words to push [^1]: tail words.
+
+padding words to push the risky token over the edge padding words to push the - item tail words.
+
+padding words to push the risky token over the edge padding words to push the # not a heading tail words.
+
+padding words to push the risky token over the edge padding words to push the > not a quote tail words.
+
+<!-- A kept line break whose next line loses its indentation is dropped the same way: printed at the line start, the row would be a table delimiter -->
+
+| x | y | |---|---|
+
+text then - item
+
+---------------------------------------
+{ printWidth: 100, proseWrap: "never" }
+---------------------------------------
+<!-- A word that would open a block at a line start never begins a wrapped line:
+     the parser's `lexical::line_start` decides, not a list of markers -->
+
+padding words to push the risky token over the edge padding words to push <!-- c --> tail words.
+
+padding words to push the risky token over the edge padding words to <div>x</div> tail words.
+
+padding words to push the risky token over the edge padding words to push the *** tail words.
+
+padding words to push the risky token over the edge padding words to push the --- tail words.
+
+padding words to push the risky token over the edge padding words to push the 1. tail words.
+
+padding words to push the risky token over the edge padding words to push the ``` tail words.
+
+padding words to push the risky token over the edge padding words to push the | a | tail words.
+
+padding words to push the risky token over the edge padding words to push [^1]: tail words.
+
+padding words to push the risky token over the edge padding words to push the - item tail words.
+
+padding words to push the risky token over the edge padding words to push the # not a heading tail words.
+
+padding words to push the risky token over the edge padding words to push the > not a quote tail words.
+
+<!-- A kept line break whose next line loses its indentation is dropped the same way: printed at the line start, the row would be a table delimiter -->
+
+| x | y | |---|---|
+
+text then - item
+
+-----------------------------------------
+{ printWidth: 80, proseWrap: "preserve" }
+-----------------------------------------
+<!-- A word that would open a block at a line start never begins a wrapped line:
+     the parser's `lexical::line_start` decides, not a list of markers -->
+
+padding words to push the risky token over the edge padding words to push <!-- c --> tail words.
+
+padding words to push the risky token over the edge padding words to <div>x</div> tail words.
+
+padding words to push the risky token over the edge padding words to push the *** tail words.
+
+padding words to push the risky token over the edge padding words to push the --- tail words.
+
+padding words to push the risky token over the edge padding words to push the 1. tail words.
+
+padding words to push the risky token over the edge padding words to push the ``` tail words.
+
+padding words to push the risky token over the edge padding words to push the | a | tail words.
+
+padding words to push the risky token over the edge padding words to push [^1]: tail words.
+
+padding words to push the risky token over the edge padding words to push the - item tail words.
+
+padding words to push the risky token over the edge padding words to push the # not a heading tail words.
+
+padding words to push the risky token over the edge padding words to push the > not a quote tail words.
+
+<!-- A kept line break whose next line loses its indentation is dropped the same way: printed at the line start, the row would be a table delimiter -->
+
+| x | y | |---|---|
+
+text then - item
+
+------------------------------------------
+{ printWidth: 100, proseWrap: "preserve" }
+------------------------------------------
+<!-- A word that would open a block at a line start never begins a wrapped line:
+     the parser's `lexical::line_start` decides, not a list of markers -->
+
+padding words to push the risky token over the edge padding words to push <!-- c --> tail words.
+
+padding words to push the risky token over the edge padding words to <div>x</div> tail words.
+
+padding words to push the risky token over the edge padding words to push the *** tail words.
+
+padding words to push the risky token over the edge padding words to push the --- tail words.
+
+padding words to push the risky token over the edge padding words to push the 1. tail words.
+
+padding words to push the risky token over the edge padding words to push the ``` tail words.
+
+padding words to push the risky token over the edge padding words to push the | a | tail words.
+
+padding words to push the risky token over the edge padding words to push [^1]: tail words.
+
+padding words to push the risky token over the edge padding words to push the - item tail words.
+
+padding words to push the risky token over the edge padding words to push the # not a heading tail words.
+
+padding words to push the risky token over the edge padding words to push the > not a quote tail words.
+
+<!-- A kept line break whose next line loses its indentation is dropped the same way: printed at the line start, the row would be a table delimiter -->
+
+| x | y | |---|---|
+
+text then - item
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/single-tilde.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/single-tilde.md
new file mode 100644
index 0000000000..5f1dc1ac49
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/single-tilde.md
@@ -0,0 +1,3 @@
+<!-- `~x~` is not strikethrough (GitHub only strikes `~~x~~`); it is kept as written -->
+
+H~2~O and ~~struck~~ text.
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/single-tilde.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/single-tilde.md.snap
new file mode 100644
index 0000000000..b43f9c65c3
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/single-tilde.md.snap
@@ -0,0 +1,24 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+<!-- `~x~` is not strikethrough (GitHub only strikes `~~x~~`); it is kept as written -->
+
+H~2~O and ~~struck~~ text.
+
+==================== Output ====================
+------------------
+{ printWidth: 80 }
+------------------
+<!-- `~x~` is not strikethrough (GitHub only strikes `~~x~~`); it is kept as written -->
+
+H~2~O and ~~struck~~ text.
+
+-------------------
+{ printWidth: 100 }
+-------------------
+<!-- `~x~` is not strikethrough (GitHub only strikes `~~x~~`); it is kept as written -->
+
+H~2~O and ~~struck~~ text.
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/indented-code-block.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/indented-code-block.md
new file mode 100644
index 0000000000..e2afadbff1
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/indented-code-block.md
@@ -0,0 +1,17 @@
+- [x] task item
+
+      indented code
+
+- unordered item
+
+      indented code
+
+- outer item
+
+  - nested item
+
+        indented code
+
+- item with extra code indentation
+
+          indented code
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/indented-code-block.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/indented-code-block.md.snap
new file mode 100644
index 0000000000..ccb84450d6
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/indented-code-block.md.snap
@@ -0,0 +1,66 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+- [x] task item
+
+      indented code
+
+- unordered item
+
+      indented code
+
+- outer item
+
+  - nested item
+
+        indented code
+
+- item with extra code indentation
+
+          indented code
+
+==================== Output ====================
+-------------------------------
+{ printWidth: 80, tabWidth: 4 }
+-------------------------------
+- [x] task item
+
+      indented code
+
+- unordered item
+
+      indented code
+
+- outer item
+
+    - nested item
+
+          indented code
+
+- item with extra code indentation
+
+          indented code
+
+--------------------------------
+{ printWidth: 100, tabWidth: 4 }
+--------------------------------
+- [x] task item
+
+      indented code
+
+- unordered item
+
+      indented code
+
+- outer item
+
+    - nested item
+
+          indented code
+
+- item with extra code indentation
+
+          indented code
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-html-block.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-html-block.md
new file mode 100644
index 0000000000..9e9e610f1d
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-html-block.md
@@ -0,0 +1,23 @@
+1. Enable images:
+
+    ```json
+    {}
+    ```
+
+    <p align="center">
+      <img alt="example">
+    </p>
+
+2. Continue.
+
+- item
+
+    <div>
+      html at the content column plus one
+    </div>
+
+- [ ] task item
+
+    <textarea>
+    stays in the item
+    </textarea>
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-html-block.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-html-block.md.snap
new file mode 100644
index 0000000000..56319ba4f1
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-html-block.md.snap
@@ -0,0 +1,84 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+1. Enable images:
+
+    ```json
+    {}
+    ```
+
+    <p align="center">
+      <img alt="example">
+    </p>
+
+2. Continue.
+
+- item
+
+    <div>
+      html at the content column plus one
+    </div>
+
+- [ ] task item
+
+    <textarea>
+    stays in the item
+    </textarea>
+
+==================== Output ====================
+-------------------------------
+{ printWidth: 80, tabWidth: 4 }
+-------------------------------
+1. Enable images:
+
+    ```json
+    {}
+    ```
+
+    <p align="center">
+      <img alt="example">
+    </p>
+
+2. Continue.
+
+- item
+
+    <div>
+      html at the content column plus one
+    </div>
+
+- [ ] task item
+
+    <textarea>
+    stays in the item
+    </textarea>
+
+--------------------------------
+{ printWidth: 100, tabWidth: 4 }
+--------------------------------
+1. Enable images:
+
+    ```json
+    {}
+    ```
+
+    <p align="center">
+      <img alt="example">
+    </p>
+
+2. Continue.
+
+- item
+
+    <div>
+      html at the content column plus one
+    </div>
+
+- [ ] task item
+
+    <textarea>
+    stays in the item
+    </textarea>
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-indented-code.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-indented-code.md
new file mode 100644
index 0000000000..f12dd19540
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-indented-code.md
@@ -0,0 +1,14 @@
+- foo
+
+  bar
+
+      indented code in a bullet item
+      second line
+
+- [ ] task
+
+          indented code in a task item
+          second line
+
+>2.     ordered item starting with indented code
+>        second line
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-indented-code.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-indented-code.md.snap
new file mode 100644
index 0000000000..5238c0b6fe
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/list-indented-code.md.snap
@@ -0,0 +1,57 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+- foo
+
+  bar
+
+      indented code in a bullet item
+      second line
+
+- [ ] task
+
+          indented code in a task item
+          second line
+
+>2.     ordered item starting with indented code
+>        second line
+
+==================== Output ====================
+-------------------------------
+{ printWidth: 80, tabWidth: 4 }
+-------------------------------
+- foo
+
+    bar
+
+      indented code in a bullet item
+      second line
+
+- [ ] task
+
+          indented code in a task item
+          second line
+
+> 2.     ordered item starting with indented code
+>        second line
+
+--------------------------------
+{ printWidth: 100, tabWidth: 4 }
+--------------------------------
+- foo
+
+    bar
+
+      indented code in a bullet item
+      second line
+
+- [ ] task
+
+          indented code in a task item
+          second line
+
+> 2.     ordered item starting with indented code
+>        second line
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/options.json b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/options.json
new file mode 100644
index 0000000000..73bf03b43f
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/tab-width-4/options.json
@@ -0,0 +1 @@
+[{ "tabWidth": 4 }]
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/thematic-break-first.md b/crates/oxc_formatter_markdown/tests/fixtures/markdown/thematic-break-first.md
new file mode 100644
index 0000000000..2d5bc80d2c
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/thematic-break-first.md
@@ -0,0 +1,5 @@
+---
+
+A document that opens with a thematic break.
+
+---
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/markdown/thematic-break-first.md.snap b/crates/oxc_formatter_markdown/tests/fixtures/markdown/thematic-break-first.md.snap
new file mode 100644
index 0000000000..df85404c03
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/markdown/thematic-break-first.md.snap
@@ -0,0 +1,30 @@
+---
+source: crates/oxc_formatter_markdown/tests/fixtures/mod.rs
+---
+==================== Input ====================
+---
+
+A document that opens with a thematic break.
+
+---
+
+==================== Output ====================
+------------------
+{ printWidth: 80 }
+------------------
+***
+
+A document that opens with a thematic break.
+
+---
+
+-------------------
+{ printWidth: 100 }
+-------------------
+***
+
+A document that opens with a thematic break.
+
+---
+
+===================== End =====================
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/mod.rs b/crates/oxc_formatter_markdown/tests/fixtures/mod.rs
new file mode 100644
index 0000000000..e02649d6c6
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/mod.rs
@@ -0,0 +1,83 @@
+use std::path::Path;
+
+use oxc_allocator::Allocator;
+use oxc_formatter_markdown::{MarkdownFormatOptions, format, parse_for_format};
+use oxc_formatter_tests::{FixtureFormatter, OptionSet, build_fixture_snapshot};
+
+mod fingerprint;
+mod options;
+use options::apply_markdown_options;
+
+struct MarkdownHarness;
+
+impl FixtureFormatter for MarkdownHarness {
+    type Options = MarkdownFormatOptions;
+    /// The semantic fingerprint (see `fingerprint.rs`): `parse(format(x)) ≅ parse(x)`.
+    type Fingerprint = String;
+
+    fn parse_options(json: &OptionSet) -> Self::Options {
+        let mut options = MarkdownFormatOptions::default();
+        apply_markdown_options(&mut options, json);
+        options
+    }
+
+    fn format(source: &str, _path: &Path, options: &Self::Options) -> String {
+        let allocator = Allocator::default();
+        format(&allocator, source, *options)
+            .expect("format should succeed")
+            .print()
+            .expect("print should succeed")
+            .into_code()
+    }
+
+    fn fingerprint(source: &str, _path: &Path, _options: &Self::Options) -> String {
+        let allocator = Allocator::default();
+        let parsed = parse_for_format(&allocator, source).expect("source should parse");
+        fingerprint::fingerprint(parsed.source, parsed.root)
+    }
+}
+
+fn test_file(path: &Path) {
+    // `insta::assert_snapshot!` is invoked from this file so the snapshot's
+    // `source:` header records this consumer crate, not the shared harness.
+    let snap = build_fixture_snapshot::<MarkdownHarness>(path);
+    insta::with_settings!({
+        snapshot_path => snap.path,
+        prepend_module_to_snapshot => false,
+        snapshot_suffix => "",
+        omit_expression => true,
+    }, {
+        insta::assert_snapshot!(snap.name, snap.body);
+    });
+}
+
+// Include auto-generated test functions from build.rs
+include!(concat!(env!("OUT_DIR"), "/generated_tests.rs"));
+
+// ---
+
+/// Prettier prints an empty document as the empty string.
+#[test]
+fn empty_document() {
+    let allocator = Allocator::default();
+    for source in ["", "\n", "\n\n  \n"] {
+        let formatted = format(&allocator, source, MarkdownFormatOptions::default())
+            .expect("empty input should parse")
+            .print()
+            .expect("print should succeed")
+            .into_code();
+        assert_eq!(formatted, "", "{source:?}");
+    }
+}
+
+/// A leading BOM is preserved (Prettier does the same).
+#[test]
+fn bom_is_preserved() {
+    let allocator = Allocator::default();
+    let formatted = format(&allocator, "\u{feff}# Title", MarkdownFormatOptions::default())
+        .expect("BOM input should parse")
+        .print()
+        .expect("print should succeed")
+        .into_code();
+    assert_eq!(formatted, "\u{feff}# Title\n");
+}
diff --git a/crates/oxc_formatter_markdown/tests/fixtures/options.rs b/crates/oxc_formatter_markdown/tests/fixtures/options.rs
new file mode 100644
index 0000000000..a9b5ec3195
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/fixtures/options.rs
@@ -0,0 +1,42 @@
+//! Prettier option-set → `MarkdownFormatOptions` mapping.
+//!
+//! Shared by the fixture harness and the conformance target via `#[path]`
+//! (one source, no drift; see `oxc_formatter_tests`'s AGENTS.md).
+
+use oxc_formatter_core::IndentWidth;
+use oxc_formatter_markdown::{MarkdownFormatOptions, ProseWrap};
+use oxc_formatter_tests::{OptionSet, apply_core_options};
+
+/// Applies the four core options plus the Markdown-specific keys onto `options`.
+/// Parsing is lenient like `apply_core_options`: unknown or invalid values are ignored.
+pub fn apply_markdown_options(options: &mut MarkdownFormatOptions, json: &OptionSet) {
+    apply_core_options(options, json);
+    // Prettier accepts any `tabWidth`; `IndentWidth` caps at 24.
+    // Every markdown use of it clamps or takes a remainder,
+    // so the cap prints the same (the suite's `tabWidth: 999` cases).
+    if let Some(width) = json.get("tabWidth").and_then(serde_json::Value::as_u64)
+        && width > u64::from(IndentWidth::MAX)
+    {
+        options.indent_width = IndentWidth::try_from(IndentWidth::MAX).unwrap();
+    }
+
+    for (key, value) in json {
+        match key.as_str() {
+            "proseWrap" => {
+                if let Some(s) = value.as_str() {
+                    options.prose_wrap = match s {
+                        "always" => ProseWrap::Always,
+                        "never" => ProseWrap::Never,
+                        _ => ProseWrap::Preserve,
+                    };
+                }
+            }
+            "singleQuote" => {
+                if let Some(b) = value.as_bool() {
+                    options.single_quote = b.into();
+                }
+            }
+            _ => {}
+        }
+    }
+}
diff --git a/crates/oxc_formatter_markdown/tests/invariants.rs b/crates/oxc_formatter_markdown/tests/invariants.rs
new file mode 100644
index 0000000000..97126e4c33
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/invariants.rs
@@ -0,0 +1,303 @@
+//! Fuzzed safety invariants (the parser repo's differential corpus, formatted instead of compared):
+//!
+//! 1. `parse(format(x)) ≅ parse(x)` (the fixture fingerprint)
+//! 2. `format(format(x)) == format(x)`
+//!
+//! under every `proseWrap`.
+//! Deterministic; the default corpus must fail exactly on the known documents (`KNOWN_FAILURES`),
+//! any other corpus reports every failure:
+//! `MD_FUZZ_COUNT=50000 MD_FUZZ_SEED=7 cargo test -p oxc_formatter_markdown --test invariants`.
+//! `MD_FUZZ_FILE=path` prints one document's fingerprints.
+
+#![expect(clippy::print_stderr)] // the failure reports
+
+use oxc_allocator::Allocator;
+use oxc_formatter_core::{IndentWidth, LineWidth};
+use oxc_formatter_markdown::{MarkdownFormatOptions, ProseWrap, format, parse_for_format};
+
+#[path = "fixtures/fingerprint.rs"]
+mod fingerprint;
+
+/// The differential runner's token soup (`tasks/differential/run.ts` in the parser repo).
+const TOKENS: &[&str] = &[
+    "*",
+    "**",
+    "_",
+    "__",
+    "`",
+    "``",
+    "[",
+    "]",
+    "(",
+    ")",
+    "<",
+    ">",
+    "#",
+    "##",
+    "-",
+    "+",
+    "1.",
+    "2)",
+    ">",
+    "\\",
+    "&",
+    "&amp;",
+    "&#35;",
+    "!",
+    "\"",
+    "'",
+    "=",
+    "~",
+    "|",
+    ":",
+    "a",
+    "foo",
+    "bar b",
+    "é",
+    "漢字",
+    "http://x.y",
+    "user@e.com",
+    "\\*",
+    "\\\\",
+    " ",
+    "  ",
+    "\t",
+    "\n",
+    "\n\n",
+    "  \n",
+    "\\\n",
+    "```\n",
+    "---",
+    "===",
+    "***",
+    "    ",
+    "[x]: /u",
+    "[x]",
+    "\"t\"",
+    "'t'",
+    "<div>",
+    "</div>",
+    "<!-- c -->",
+    "![",
+    "](u)",
+    "<a>",
+    "<span x=1>",
+    "</span>",
+    "> x\n<a>\n",
+    "<script>",
+    "</script>",
+    "<pre x>",
+    "</pre>",
+    "<textarea>\n",
+    "<style",
+    "</style>",
+    "~~",
+    "~",
+    "[^1]",
+    "[^1]: n",
+    "- [x] ",
+    "- [ ] ",
+    "| a | b |",
+    "| - | - |",
+    "-|-",
+    ":-:",
+    "www.a.com",
+    "http://x.y/p(q)",
+    "u@e.com",
+    "W",
+    "h",
+    "[σ]: /u",
+    "[ς]",
+    "[ff]: /u",
+    "[ff]",
+    "\u{3000}",
+    "\u{2E53}",
+    "\u{FDFE}",
+    "😀",
+    "$",
+    "$$",
+    "$$\n",
+    "$x$",
+    "$$m\n",
+    "{%",
+    "%}",
+    "{{",
+    "}}",
+    "{{ v }}",
+    "{% t %}",
+    "[[",
+    "]]",
+    "[[w]]",
+    ":::",
+    "::::",
+    ":::\n",
+    ":::note\n",
+    ":::note",
+    "::::a\n",
+    "[l]",
+    "{.c}",
+    ":::a[l]{#i k=v}\n",
+    "::: tip Title\n",
+    "    a\n",
+    "    \n",
+    "\t\n",
+    "      \n",
+    "  \t\r\n",
+    "\r\n",
+    "  \r\n",
+    // Prose shapes the formatter wraps: CJK runs, long words, alerts, component tags
+    "日本語の文章",
+    "한국어 단어",
+    "、",
+    "。",
+    "「",
+    "」",
+    "…",
+    "〜",
+    "English words",
+    "[!NOTE]",
+    "<Badge />",
+    "<<< @/f.js",
+    "(paren)",
+    "a * b",
+    "2. ",
+];
+
+// The default corpus (seed 0, 3000 documents) fails exactly on these documents.
+// Any failure is a regression; a new known class goes here with its description.
+// Other seeds are close to 0 too; what remains there is a lazy line inside a liquid tag
+// (re-indenting the continuation turns the tag into a flow block).
+const KNOWN_FAILURES: &[(usize, ProseWrap)] = &[];
+
+/// The runner's `Rng` (mulberry32), so a seed names the same document on both sides.
+struct Rng(u32);
+
+impl Rng {
+    fn next(&mut self) -> u32 {
+        self.0 = self.0.wrapping_add(0x6d2b_79f5);
+        let mut t = self.0;
+        t = (t ^ (t >> 15)).wrapping_mul(t | 1);
+        t ^= t.wrapping_add((t ^ (t >> 7)).wrapping_mul(t | 0x3d));
+        t ^ (t >> 14)
+    }
+
+    /// The runner's `Math.floor(random() * (hi - lo + 1)) + lo`, in integers (the product fits).
+    fn int(&mut self, lo: usize, hi: usize) -> usize {
+        let n = (u64::from(self.next()) * (hi - lo + 1) as u64) >> 32;
+        lo + usize::try_from(n).unwrap()
+    }
+
+    fn soup(&mut self, n: usize) -> String {
+        std::iter::repeat_with(|| TOKENS[self.int(0, TOKENS.len() - 1)]).take(n).collect()
+    }
+}
+
+fn format_source(source: &str, options: MarkdownFormatOptions) -> Option<String> {
+    let allocator = Allocator::default();
+    Some(format(&allocator, source, options).ok()?.print().ok()?.into_code())
+}
+
+fn fingerprint_of(source: &str) -> String {
+    let allocator = Allocator::default();
+    let parsed = parse_for_format(&allocator, source).expect("source should parse");
+    fingerprint::fingerprint(parsed.source, parsed.root)
+}
+
+fn first_difference<'a>(before: &'a str, after: &'a str) -> (&'a str, &'a str) {
+    let mut a = after.lines();
+    for b in before.lines() {
+        match a.next() {
+            Some(l) if l == b => {}
+            Some(l) => return (b, l),
+            None => return (b, "<end>"),
+        }
+    }
+    ("<end>", a.next().unwrap_or("<end>"))
+}
+
+/// `MD_FUZZ_FILE=path`: the invariants of one document, with the full fingerprints
+/// (`MD_FUZZ_WIDTH` / `MD_FUZZ_TAB_WIDTH` override the corpus options).
+#[test]
+fn single_file() {
+    let Ok(path) = std::env::var("MD_FUZZ_FILE") else { return };
+    let source = std::fs::read_to_string(path).unwrap();
+    let env = |name: &str, default: u16| -> u16 {
+        std::env::var(name).ok().and_then(|v| v.parse().ok()).unwrap_or(default)
+    };
+    let line_width = LineWidth::try_from(env("MD_FUZZ_WIDTH", 40)).unwrap();
+    let indent_width =
+        IndentWidth::try_from(u8::try_from(env("MD_FUZZ_TAB_WIDTH", 2)).unwrap()).unwrap();
+    for prose_wrap in [ProseWrap::Preserve, ProseWrap::Always, ProseWrap::Never] {
+        let options = MarkdownFormatOptions {
+            prose_wrap,
+            line_width,
+            indent_width,
+            ..MarkdownFormatOptions::default()
+        };
+        let once = format_source(&source, options).unwrap();
+        let twice = format_source(&once, options).unwrap();
+        eprintln!(
+            "=== {prose_wrap:?}\n--- once\n{once}--- before\n{}--- after\n{}--- idempotent: {}",
+            fingerprint_of(&source),
+            fingerprint_of(&once),
+            once == twice
+        );
+    }
+}
+
+#[test]
+fn fuzzed_invariants() {
+    let count: usize =
+        std::env::var("MD_FUZZ_COUNT").ok().and_then(|v| v.parse().ok()).unwrap_or(3000);
+    let seed: u32 = std::env::var("MD_FUZZ_SEED").ok().and_then(|v| v.parse().ok()).unwrap_or(0);
+    let mut rng = Rng(seed);
+    let mut failures: Vec<((usize, ProseWrap), String)> = Vec::new();
+    for i in 0..count {
+        let n = rng.int(2, 40);
+        let source = rng.soup(n).trim_end_matches('\n').to_string() + "\n";
+        for prose_wrap in [ProseWrap::Preserve, ProseWrap::Always, ProseWrap::Never] {
+            let options = MarkdownFormatOptions {
+                prose_wrap,
+                line_width: LineWidth::try_from(40).unwrap(),
+                ..MarkdownFormatOptions::default()
+            };
+            let Some(once) = format_source(&source, options) else {
+                failures.push(((i, prose_wrap), format!("format failed\n{source:?}")));
+                continue;
+            };
+            let before = fingerprint_of(&source);
+            let after = fingerprint_of(&once);
+            if before != after {
+                let (b, a) = first_difference(&before, &after);
+                failures.push((
+                    (i, prose_wrap),
+                    format!("meaning changed\ninput: {source:?}\noutput: {once:?}\nbefore: {b}\nafter:  {a}"),
+                ));
+                continue;
+            }
+            let twice = format_source(&once, options).unwrap_or_default();
+            if twice != once {
+                failures.push((
+                    (i, prose_wrap),
+                    format!("not idempotent\ninput: {source:?}\nonce: {once:?}\ntwice: {twice:?}"),
+                ));
+            }
+        }
+    }
+    let known: &[(usize, ProseWrap)] =
+        if count == 3000 && seed == 0 { KNOWN_FAILURES } else { &[] };
+    let failed: Vec<_> = failures.iter().map(|(key, _)| *key).collect();
+    if failed != known {
+        let report: Vec<_> = failures
+            .iter()
+            .take(60)
+            .map(|((i, prose_wrap), what)| format!("#{i} {prose_wrap:?}: {what}"))
+            .collect();
+        eprintln!(
+            "{} of {count} documents (seed {seed}) broke an invariant; first 60:\n\n{}",
+            failures.len(),
+            report.join("\n\n")
+        );
+    }
+    assert_eq!(failed, known, "failures on seed {seed} differ from the known ones");
+}
diff --git a/crates/oxc_formatter_markdown/tests/mod.rs b/crates/oxc_formatter_markdown/tests/mod.rs
new file mode 100644
index 0000000000..681564e4bf
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/mod.rs
@@ -0,0 +1 @@
+mod fixtures;
diff --git a/crates/oxc_formatter_markdown/tests/snapshots/conformance__prettier-markdown.snap b/crates/oxc_formatter_markdown/tests/snapshots/conformance__prettier-markdown.snap
new file mode 100644
index 0000000000..27cf0d5c78
--- /dev/null
+++ b/crates/oxc_formatter_markdown/tests/snapshots/conformance__prettier-markdown.snap
@@ -0,0 +1,26 @@
+---
+source: crates/oxc_formatter_markdown/tests/conformance.rs
+expression: report
+---
+markdown compatibility: 1246/1262 (98.73%), 0 files skipped
+
+# Failed
+
+| Spec path | Failed or Passed | Match ratio |
+| :-------- | :--------------: | :---------: |
+| markdown/blockquote/notext-end.md | 💥💥✨ | 60.74% |
+| markdown/commonmark-test-suite/snippet: example-11.md (Tabs) | 💥 | 0.00% |
+| markdown/commonmark-test-suite/snippet: example-2.md (Tabs) | 💥 | 0.00% |
+| markdown/commonmark-test-suite/snippet: example-412.md (Emphasis and strong emphasis) | 💥 | 0.00% |
+| markdown/commonmark-test-suite/snippet: example-50.md (Thematic breaks) | 💥 | 0.00% |
+| markdown/commonmark-test-suite/snippet: example-51.md (Thematic breaks) | 💥 | 0.00% |
+| markdown/commonmark-test-suite/snippet: example-52.md (Thematic breaks) | 💥 | 0.00% |
+| markdown/commonmark-test-suite/snippet: example-53.md (Thematic breaks) | 💥 | 0.00% |
+| markdown/commonmark-test-suite/snippet: example-54.md (Thematic breaks) | 💥 | 0.00% |
+| markdown/gfm-test-suite/snippet: example-491.md (6.5 Strikethrough (extension)) | 💥 | 0.00% |
+| markdown/link/encodedLink.md | 💥 | 86.67% |
+| markdown/liquid/character-after-closing-tokens.md | 💥✨ | 41.18% |
+| markdown/liquid/example-1.md | 💥✨ | 43.48% |
+| markdown/liquid/example-2.md | 💥💥 | 90.48% |
+| markdown/paragraph/cjk.md | 💥💥✨ | 60.00% |
+| markdown/thematicBreak/simple.md | 💥 | 0.00% |
diff --git a/oxc_release.toml b/oxc_release.toml
index 049c5197b1..86bc3907e8 100644
--- a/oxc_release.toml
+++ b/oxc_release.toml
@@ -40,5 +40,6 @@ versioned_files = [
   "crates/oxc_formatter_graphql/Cargo.toml",
   "crates/oxc_formatter_css/Cargo.toml",
   "crates/oxc_formatter_yaml/Cargo.toml",
+  "crates/oxc_formatter_markdown/Cargo.toml",
   "npm/oxfmt/package.json",
 ]