Watch
1
0
Fork
You've already forked packages
0
packages/markdown/README.md
Weft packages 306b143104 packages/ at markup-kit dd1e6eb5270e
A snapshot of packages/ in the Weft repository; the official packages are published from these commits.

Markup-Kit-Commit: dd1e6eb5270e62e0c8b6c202b3d01f0da6e00ddc
2026-11-19 20:43:26 +00:00

4.4 KiB

@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.

weft add weft/markdown
import { parse, render, sanitize, toHtml, toText, visit } from "@weft/markdown"

toHtml("# Hello\n\n**bold** <script>alert(1)</script>")
// <h1>Hello</h1>
// <p><strong>bold</strong> &lt;script&gt;alert(1)&lt;/script&gt;</p>

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 <input> 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.
toHtml("a <kbd>b</kbd> <script>c()</script>", { html: "sanitize" })   // <p>a <kbd>b</kbd> </p>
sanitize("<a href=\"javascript:x()\" onclick=\"y()\">hi</a>")          // <a>hi</a>

Options

toHtml(source, {
  headingOffset: 1,                 // `# Title` renders as <h2>
  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:<id>) 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 <strong>, 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

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=<its folder>)
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