@headwall/markdown-to-blocks 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.4.0] - 2026-11-20
11
+
12
+ ### Security
13
+
14
+ - **Link and image URLs are now restricted to safe schemes by default**
15
+ (`urlSchemes: 'safe'`). Links keep their `href` only for `http:`, `https:`,
16
+ `mailto:`, `tel:` and relative URLs, otherwise only the link text renders.
17
+ Images need `http:`, `https:` or a relative URL, otherwise they are dropped.
18
+ This covers inline, reference-style and resolver-supplied URLs, and reads
19
+ schemes as a browser does (case, embedded tabs/newlines, leading
20
+ whitespace). `urlSchemes: 'any'` / `--url-schemes any` restores the old
21
+ pass-through.
22
+ - `unsupported: 'skip'` now drops inline HTML too. Previously only block HTML
23
+ was dropped, so inline markup, including a `<!-- wp:… -->` comment that
24
+ injects a block, survived in skip mode.
25
+ - Fenced code blocks now apply core/code's own save-time escaping: `[` becomes
26
+ `&#91;` and the first URL alone on its line has its `//` escaped. Shortcodes
27
+ in code examples previously ran on the front end, and the output didn't match
28
+ what the block editor saves.
29
+ - `resolveImage` must return a positive integer `id`; anything else throws a
30
+ `RangeError`. A malformed id could previously break out of the image's
31
+ `class` attribute.
32
+ - Markdown nesting deeper than 200 levels throws a `RangeError` naming the
33
+ depth, instead of overflowing the call stack (about 3,000 nested `>` was
34
+ enough).
35
+
36
+ ### Fixed
37
+
38
+ - Ordered lists that don't start at 1 (`3. Three`) kept their numbering in
39
+ Markdown but were renumbered from 1 in WordPress. They now carry `start` in
40
+ the block attributes and on the `<ol>`, matching core's serialiser.
41
+ - With `codeLanguage: 'class'`, the fence language was written into the `class`
42
+ attribute unescaped, so a language containing `"` broke out of the attribute
43
+ and produced an invalid block. It is now attribute-escaped.
44
+ - A resolver-supplied `sizeSlug` is now escaped in both the `wp:image`
45
+ attributes (as core's serialiser does, so `-->` can't close the comment) and
46
+ the figure's `size-…` class.
47
+ - Invalid options no longer produce invalid markup (`<hNaN>`, `<h0>`). All
48
+ conversion functions now throw a `RangeError` listing every invalid option:
49
+ `headingShift` must be an integer, `minHeadingLevel` an integer from 1 to 6,
50
+ and `codeLanguage` / `unsupported` one of their documented modes. Unknown
51
+ mode strings were previously treated as the default.
52
+ - The CLI no longer silently ignores unknown options, flags missing their
53
+ value, non-integer numbers or extra file arguments. It reports every problem
54
+ together and exits 1 without converting.
55
+
56
+ ### Changed
57
+
58
+ - Output is now validated against `@wordpress/block-library` 12 and
59
+ `@wordpress/blocks` 17 (dev-only). Dev tooling refreshed: tsup 9, jsdom 31,
60
+ vitest 5.1. Bundled runtime code is unchanged, and the built JavaScript is
61
+ byte-identical between tsup 8 and 9. Clears a dev-only `undici` advisory
62
+ (via jsdom).
63
+
64
+ ## [1.3.0] - 2026-10-06
65
+
66
+ ### Fixed
67
+
68
+ - CLI output written to a pipe (`md2blocks -i post.md | …`, `$(md2blocks …)`,
69
+ `child_process`) was silently cut off at 64 KB with exit code 0, because the
70
+ CLI called `process.exit()` before stdout had drained. Output to a file or
71
+ via `-o` was unaffected. The CLI now sets `process.exitCode` and lets stdout
72
+ drain.
73
+
74
+ ### Changed
75
+
76
+ - **Require Node ≥ 22** (was ≥ 20). Node 20 is end-of-life; CI now tests
77
+ Node 22 and 24, and the build targets `node22`.
78
+ - When the reader closes the pipe early (`md2blocks … | head`), the CLI exits
79
+ quietly with code 141, as a SIGPIPE-killed process would, so `set -o pipefail`
80
+ scripts can detect the incomplete output.
81
+ - Bundled `yaml` updated to 2.9.1. Output is now validated against
82
+ `@wordpress/block-library` 11 and `@wordpress/blocks` 16 (dev-only).
83
+
10
84
  ## [1.2.0] - 2026-07-05
11
85
 
12
86
  ### Added
@@ -78,7 +152,9 @@ parser and confirmed to import into the block editor with no recovery prompts.
78
152
  - ESM-only. Requires Node ≥ 18.
79
153
  - Zero runtime dependencies — all bundled into the published package.
80
154
 
81
- [Unreleased]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.2.0...HEAD
155
+ [Unreleased]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.4.0...HEAD
156
+ [1.4.0]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.3.0...v1.4.0
157
+ [1.3.0]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.2.0...v1.3.0
82
158
  [1.2.0]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.1.1...v1.2.0
83
159
  [1.1.1]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.1.0...v1.1.1
84
160
  [1.1.0]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.0.0...v1.1.0
package/README.md CHANGED
@@ -25,7 +25,7 @@
25
25
  npm install -g @headwall/markdown-to-blocks
26
26
  ```
27
27
 
28
- This puts the `md2blocks` command on your `PATH`. Requires **Node ≥ 20**.
28
+ This puts the `md2blocks` command on your `PATH`. Requires **Node ≥ 22**.
29
29
 
30
30
  ### As a library
31
31
 
@@ -101,10 +101,11 @@ Modes:
101
101
 
102
102
  Conversion options:
103
103
  --heading-shift <n> Shift all heading levels by n (default 0)
104
- --min-heading-level <n> Clamp heading levels to [n, 6] (default 2)
104
+ --min-heading-level <n> Clamp heading levels to [n, 6], n from 1 to 6 (default 2)
105
105
  --heading-anchors Add an id/anchor to each heading from its text
106
106
  --code-language <mode> 'drop' (default) or 'class' (emit language-xxx)
107
- --unsupported <mode> 'html' (default, wrap in core/html) or 'skip'
107
+ --unsupported <mode> 'html' (default, wrap in core/html) or 'skip' (drop block and inline HTML)
108
+ --url-schemes <mode> 'safe' (default: http(s)/mailto/tel/relative) or 'any'
108
109
  --no-gfm Disable GFM (tables, strikethrough, autolinks)
109
110
 
110
111
  -h, --help Show help
@@ -165,9 +166,12 @@ Body text.
165
166
  | `headingAnchors` | `boolean` | `false` | Derive an `id` (WordPress `anchor` attribute) for each heading from its text, so in-page anchor links work. GitHub-style slugs, de-duplicated per document (`overview`, `overview-1`, …). A heading that slugs to nothing (only punctuation/emoji) gets no `id`. |
166
167
  | `resolveImage` | `(src, alt, title?) => ResolvedImage \| undefined` | — | Resolve a Markdown image to a WordPress image (see [Images](#images)). |
167
168
  | `codeLanguage` | `'drop' \| 'class'` | `'drop'` | `'drop'` discards the fence language (core behaviour). `'class'` emits `<code class="language-xxx">` for a syntax-highlighting plugin. |
168
- | `unsupported` | `'html' \| 'skip'` | `'html'` | How to handle raw/unsupported nodes: wrap in `core/html`, or omit. |
169
+ | `unsupported` | `'html' \| 'skip'` | `'html'` | How to handle raw HTML and unsupported nodes. `'html'`: block HTML goes into `core/html` and inline HTML passes through verbatim. `'skip'`: both are omitted. |
170
+ | `urlSchemes` | `'safe' \| 'any'` | `'safe'` | Restrict link and image URLs to safe schemes (see [URL safety](#url-safety)). `'any'` turns the check off. |
169
171
  | `gfm` | `boolean` | `true` | Enable GFM (tables, strikethrough, autolinks). |
170
172
 
173
+ Invalid option values (a non-integer `headingShift`, a `minHeadingLevel` outside 1–6, an unknown mode string) throw a `RangeError` listing every problem.
174
+
171
175
  ### `ResolvedImage`
172
176
 
173
177
  ```ts
@@ -200,6 +204,27 @@ const html = markdownToBlocks(markdown, {
200
204
 
201
205
  - When `resolveImage` returns an object **with an `id`**, you get the attachment shape: `wp:image {"id":…,"sizeSlug":…,"linkDestination":"none"}`, a `size-<slug>` figure class, and a `wp-image-<id>` class on the `<img>`.
202
206
  - When it returns `undefined`, you get the **external** fallback: a plain `<figure class="wp-block-image">` / `<img>` with no attachment id.
207
+ - An `id` must be a positive integer; anything else throws a `RangeError`.
208
+ - The final URL, whether from the Markdown or the resolver, is subject to the [URL safety](#url-safety) policy.
209
+
210
+ ---
211
+
212
+ ## Untrusted Markdown
213
+
214
+ The converter escapes text correctly, but it is **not an HTML sanitiser**. When the Markdown comes from somewhere you don't control (user input, scraped pages, another model's output):
215
+
216
+ - **Raw HTML passes through by default.** Use `unsupported: 'skip'` to drop both block and inline HTML. WordPress strips unsafe HTML on save only for accounts without the `unfiltered_html` capability, so don't rely on that when posting as an administrator.
217
+ - **Shortcodes in prose still run.** `[gallery]` in a paragraph is rendered by WordPress as a shortcode, exactly as if typed in the editor. Inside fenced code blocks `[` is escaped as `&#91;`, matching what the block editor itself saves, so code examples display literally. Inline code is not escaped: the editor would undo it on the next edit.
218
+ - **Size is the caller's to bound.** Nesting deeper than 200 levels throws a `RangeError`; overall input size is not limited, so cap it before converting if the source is untrusted.
219
+
220
+ ### URL safety
221
+
222
+ By default (`urlSchemes: 'safe'`):
223
+
224
+ - **Links** keep their `href` only for `http:`, `https:`, `mailto:`, `tel:` and relative URLs (`/about`, `#top`). Any other scheme (`javascript:`, `data:`, `vbscript:`, …) renders as the link text alone.
225
+ - **Images** need an `http:`, `https:` or relative URL; any other image is dropped.
226
+
227
+ The scheme is read the way a browser reads it, so `JAVASCRIPT:`, `java&#9;script:` and leading whitespace are all caught. Pass `urlSchemes: 'any'` (`--url-schemes any`) to turn the check off.
203
228
 
204
229
  ---
205
230
 
@@ -237,6 +262,7 @@ By default `headingShift` is `0` and `minHeadingLevel` is `2`, so a body `#` bec
237
262
  - **No interactive task-list checkboxes** — a glyph is rendered instead.
238
263
  - **No media uploads** — your agent uploads and feeds results via `resolveImage`.
239
264
  - **No block-theme / Site Editor constructs** (columns, groups, cover, etc.). Core content blocks only.
265
+ - **Nesting is capped at 200 levels** (quotes, lists and inline formatting combined).
240
266
 
241
267
  ---
242
268