@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 +75 -1
- package/README.md +49 -4
- package/dist/{chunk-FWYKR6IX.js → chunk-VRPK6PTA.js} +308 -111
- package/dist/chunk-VRPK6PTA.js.map +1 -0
- package/dist/cli.js +65 -18
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +13 -3
- package/dist/index.js +1 -1
- package/package.json +7 -7
- package/dist/chunk-FWYKR6IX.js.map +0 -1
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
|
+
(`[](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.** `` 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
|
+
`[` 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.
|
|
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
|
|
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
|
+

|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
An image wrapped in a link, alone in its paragraph, becomes a linked `core/image`:
|
|
219
|
+
|
|
220
|
+
```markdown
|
|
221
|
+
[](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 `[`, 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	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 `[](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
|
|