@headwall/markdown-to-blocks 1.3.0 → 1.5.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,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.5.0] - 2026-11-20
11
+
12
+ ### Added
13
+
14
+ - **Linked images.** A paragraph holding only a linked image
15
+ (`[![alt](src)](href)`) becomes a `core/image` with the link, instead of a
16
+ paragraph with an inline `<img>`. `linkDestination` is `"media"` when the
17
+ link is the image's own file (including WordPress's `-WxH` and `-scaled`
18
+ sizes), so lightboxes work, and `"custom"` otherwise. Link URLs follow the
19
+ `urlSchemes` policy: an unsafe link is dropped and the image renders
20
+ unlinked.
21
+ - **Captions from image titles.** `![alt](src "Caption")` renders a
22
+ `<figcaption>`. A `caption` from `resolveImage` still takes precedence.
23
+ Previously the title of an external image was silently dropped.
24
+
25
+ Both shapes are checked byte-for-byte against `@wordpress/blocks`' own
26
+ serialiser.
27
+
28
+ ## [1.4.0] - 2026-11-20
29
+
30
+ ### Security
31
+
32
+ - **Link and image URLs are now restricted to safe schemes by default**
33
+ (`urlSchemes: 'safe'`). Links keep their `href` only for `http:`, `https:`,
34
+ `mailto:`, `tel:` and relative URLs, otherwise only the link text renders.
35
+ Images need `http:`, `https:` or a relative URL, otherwise they are dropped.
36
+ This covers inline, reference-style and resolver-supplied URLs, and reads
37
+ schemes as a browser does (case, embedded tabs/newlines, leading
38
+ whitespace). `urlSchemes: 'any'` / `--url-schemes any` restores the old
39
+ pass-through.
40
+ - `unsupported: 'skip'` now drops inline HTML too. Previously only block HTML
41
+ was dropped, so inline markup, including a `<!-- wp:… -->` comment that
42
+ injects a block, survived in skip mode.
43
+ - Fenced code blocks now apply core/code's own save-time escaping: `[` becomes
44
+ `&#91;` and the first URL alone on its line has its `//` escaped. Shortcodes
45
+ in code examples previously ran on the front end, and the output didn't match
46
+ what the block editor saves.
47
+ - `resolveImage` must return a positive integer `id`; anything else throws a
48
+ `RangeError`. A malformed id could previously break out of the image's
49
+ `class` attribute.
50
+ - Markdown nesting deeper than 200 levels throws a `RangeError` naming the
51
+ depth, instead of overflowing the call stack (about 3,000 nested `>` was
52
+ enough).
53
+
54
+ ### Fixed
55
+
56
+ - Ordered lists that don't start at 1 (`3. Three`) kept their numbering in
57
+ Markdown but were renumbered from 1 in WordPress. They now carry `start` in
58
+ the block attributes and on the `<ol>`, matching core's serialiser.
59
+ - With `codeLanguage: 'class'`, the fence language was written into the `class`
60
+ attribute unescaped, so a language containing `"` broke out of the attribute
61
+ and produced an invalid block. It is now attribute-escaped.
62
+ - A resolver-supplied `sizeSlug` is now escaped in both the `wp:image`
63
+ attributes (as core's serialiser does, so `-->` can't close the comment) and
64
+ the figure's `size-…` class.
65
+ - Invalid options no longer produce invalid markup (`<hNaN>`, `<h0>`). All
66
+ conversion functions now throw a `RangeError` listing every invalid option:
67
+ `headingShift` must be an integer, `minHeadingLevel` an integer from 1 to 6,
68
+ and `codeLanguage` / `unsupported` one of their documented modes. Unknown
69
+ mode strings were previously treated as the default.
70
+ - The CLI no longer silently ignores unknown options, flags missing their
71
+ value, non-integer numbers or extra file arguments. It reports every problem
72
+ together and exits 1 without converting.
73
+
74
+ ### Changed
75
+
76
+ - Output is now validated against `@wordpress/block-library` 12 and
77
+ `@wordpress/blocks` 17 (dev-only). Dev tooling refreshed: tsup 9, jsdom 31,
78
+ vitest 5.1. Bundled runtime code is unchanged, and the built JavaScript is
79
+ byte-identical between tsup 8 and 9. Clears a dev-only `undici` advisory
80
+ (via jsdom).
81
+
10
82
  ## [1.3.0] - 2026-10-06
11
83
 
12
84
  ### Fixed
@@ -98,7 +170,9 @@ parser and confirmed to import into the block editor with no recovery prompts.
98
170
  - ESM-only. Requires Node ≥ 18.
99
171
  - Zero runtime dependencies — all bundled into the published package.
100
172
 
101
- [Unreleased]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.3.0...HEAD
173
+ [Unreleased]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.5.0...HEAD
174
+ [1.5.0]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.4.0...v1.5.0
175
+ [1.4.0]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.3.0...v1.4.0
102
176
  [1.3.0]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.2.0...v1.3.0
103
177
  [1.2.0]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.1.1...v1.2.0
104
178
  [1.1.1]: https://github.com/headwalluk/markdown-to-blocks/compare/v1.1.0...v1.1.1
package/README.md CHANGED
@@ -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,46 @@ 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
+ ### Captions and links
211
+
212
+ An image's Markdown title becomes its caption, unless the resolver supplies a `caption`:
213
+
214
+ ```markdown
215
+ ![Floor plan](https://example.com/wp-content/uploads/plan.png "Ground floor, as built")
216
+ ```
217
+
218
+ An image wrapped in a link, alone in its paragraph, becomes a linked `core/image`:
219
+
220
+ ```markdown
221
+ [![Floor plan](https://example.com/wp-content/uploads/plan-1024x768.png)](https://example.com/wp-content/uploads/plan.png)
222
+ ```
223
+
224
+ - When the link points at the image's own file, `linkDestination` is `"media"`: clicking opens the full-size image, which is what lightbox plugins and themes look for. Any size WordPress generated counts as the same file (`-1024x768`, `-scaled`), as does a relative URL with the same path.
225
+ - Any other link is `"custom"`.
226
+ - A link whose URL fails the [URL safety](#url-safety) policy is dropped, and the image renders unlinked.
227
+ - A linked image inside a sentence stays inline in its paragraph, as before.
228
+
229
+ ---
230
+
231
+ ## Untrusted Markdown
232
+
233
+ 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):
234
+
235
+ - **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.
236
+ - **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.
237
+ - **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.
238
+
239
+ ### URL safety
240
+
241
+ By default (`urlSchemes: 'safe'`):
242
+
243
+ - **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.
244
+ - **Images** need an `http:`, `https:` or relative URL; any other image is dropped.
245
+
246
+ 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
247
 
204
248
  ---
205
249
 
@@ -225,7 +269,7 @@ By default `headingShift` is `0` and `minHeadingLevel` is `2`, so a body `#` bec
225
269
  | Blockquotes | `core/quote` (with inner paragraph blocks) |
226
270
  | Thematic breaks `---` `***` `___` | `core/separator` |
227
271
  | Tables (GFM) | `core/table` |
228
- | Images | `core/image` (resolver-driven) |
272
+ | Images, linked images `[![alt](src)](href)` | `core/image` (resolver-driven; title → caption) |
229
273
  | Raw HTML in source | `core/html` |
230
274
  | **bold**, *italic*, `code`, ~~strike~~, links, hard breaks | inline HTML |
231
275
  | GFM task lists | leading `☐` / `☑` glyph (not interactive inputs) |
@@ -237,6 +281,7 @@ By default `headingShift` is `0` and `minHeadingLevel` is `2`, so a body `#` bec
237
281
  - **No interactive task-list checkboxes** — a glyph is rendered instead.
238
282
  - **No media uploads** — your agent uploads and feeds results via `resolveImage`.
239
283
  - **No block-theme / Site Editor constructs** (columns, groups, cover, etc.). Core content blocks only.
284
+ - **Nesting is capped at 200 levels** (quotes, lists and inline formatting combined).
240
285
 
241
286
  ---
242
287