# @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
```