| Filename | Latest commit message | Latest commit date |
|---|---|---|
A snapshot of packages/ in the Weft repository; the official packages are published from these commits. Markup-Kit-Commit: dd1e6eb5270e62e0c8b6c202b3d01f0da6e00ddc |
||
| .. | ||
| bench | ||
| lib | ||
| scripts | ||
| tests | ||
| ast.weft | ||
| markdown.weft | ||
| README.md | ||
| weft.toml | ||
@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> <script>alert(1)</script></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,mailtoandtel, or are relative (schemeschanges the list). Images may also bedata: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.wefttakes 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_MBandWEFT_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