# @weft/markdown CommonMark and GitHub Flavored Markdown for Weft: a syntax tree, HTML, and a sanitiser. It is written in Weft, needs no capabilities (it does no I/O), and is safe for untrusted input by default. ```sh weft add weft/markdown ``` ```weft import { parse, render, sanitize, toHtml, toText, visit } from "@weft/markdown" toHtml("# Hello\n\n**bold** ") //

Hello

//

bold <script>alert(1)</script>

``` ## What it gives you | | | |---|---| | `toHtml(source, options?)` | Markdown to HTML | | `parse(source, options?)` | the syntax tree (`Document`, typed in `@weft/markdown/ast`) | | `render(doc, options?)` | a tree to HTML, for a tree you have changed | | `toText(doc)` | plain text, for previews, search and the text part of an email | | `visit(doc, f)` | every inline of a document, to collect links or images | | `sanitize(html, policy?)` | the allowlist sanitiser on its own, for HTML from anywhere | GFM is on by default: tables, task lists, strikethrough and bare links (`www.`, `https://`, email addresses). `gfm: false` gives plain CommonMark. ## Safe by default - **Raw HTML is shown as text.** `html: "sanitize"` keeps what an allowlist permits; `html: "trust"` passes it through and is for Markdown you wrote yourself. - **Links and images only use `http`, `https`, `mailto` and `tel`**, or are relative (`schemes` changes the list). Images may also be `data:image/` PNG, GIF, JPEG or WebP, never SVG. A link that isn't allowed renders as its text. - **The sanitiser is an allowlist over a tokenizer**, and what it writes is well formed with every text escaped. Scripts, styles, frames, forms, SVG, MathML, event handlers and unsafe URLs are removed. The only `` kept is a disabled checkbox. - **Hostile documents can't take the server down.** Quotes, lists and inlines stop nesting at 64 levels, the text a link reference expands to is bounded, and every input in `tests/hostile.weft` takes time proportional to its size. ```weft toHtml("a b ", { html: "sanitize" }) //

a b

sanitize("hi") // hi ``` ## Options ```weft toHtml(source, { headingOffset: 1, // `# Title` renders as

linkTarget: "_blank", // adds rel="noopener noreferrer" rewriteUrl: (url, kind) => url.startsWith("upload:") ? cdn(url.slice(7)) : null, }) ``` `rewriteUrl` runs before the safety check, so an app's own scheme (`upload:`) can resolve to a real address, and one it can't resolve is dropped rather than rendered. ## Conformance `weft run tests/spec.weft` runs the specs' examples: | | | |---|---| | CommonMark 0.31.2 | 652 of 652 | | GitHub Flavored Markdown | 660 of 669, and the other 9 are below | The 9 are examples where the two specs give different HTML for the same text: the GFM spec was written against CommonMark 0.29, and its renderer folds nested ``, which CommonMark 0.31.2's own examples keep. This package follows CommonMark there, and the runner checks each such example against CommonMark's expected output. GFM's `tagfilter` example isn't run: `html: "escape"` and `"sanitize"` already remove those tags, and `"trust"` means what it says. ## Speed Against markdown-it 15.0.3 on Node 24, rendering the CommonMark spec's examples joined and repeated (`scripts/bench.mjs`; one cold run each, in a 6 GB container, so markdown-it's JIT is warming up over the small sizes): | document | Weft VM | markdown-it (JIT) | markdown-it (`--jitless`) | |---|---|---|---| | 16 KB | 52 ms | 44 ms | 47 ms | | 157 KB | 112 ms | 105 ms | 242 ms | | 787 KB | 1.2 s | 0.54 s | 1.6 s | | 3.1 MB | 5.3 s | 1.5 s | 5.7 s | ## Limits - A turn's default limits (32 MB of allocation, and 250 ms when serving) fit documents up to about 150 KB. Above that, raise `WEFT_MEMORY_MB` and `WEFT_DEADLINE_MS`, or render outside a request. ## Development ```sh weft test tests/markdown.test.weft # the API and its safety weft run tests/spec.weft # the specs' examples (-v prints each failure) node scripts/hostile.mjs # hostile input: nothing stops, nothing is quadratic node scripts/bench.mjs commonmark.json # beside markdown-it (MARKDOWN_IT=) node scripts/gen-spec.mjs # regenerates tests/cases.weft from the specs node scripts/gen-tables.mjs # regenerates lib/entities.weft and lib/unicode.weft ```