A snapshot of packages/ in the Weft repository; the official packages are published from these commits. Markup-Kit-Commit: dd1e6eb5270e62e0c8b6c202b3d01f0da6e00ddc
102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# @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** <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`, `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.
|
|
|
|
```weft
|
|
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
|
|
|
|
```weft
|
|
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
|
|
|
|
```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=<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
|
|
```
|