@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 +77 -1
- package/README.md +30 -4
- package/dist/{chunk-CHMDS2SX.js → chunk-26IEHNWU.js} +947 -645
- package/dist/chunk-26IEHNWU.js.map +1 -0
- package/dist/cli.js +81 -22
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +13 -3
- package/dist/index.js +1 -1
- package/package.json +10 -9
- package/dist/chunk-CHMDS2SX.js.map +0 -1
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
|
+
`[` 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.
|
|
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 ≥
|
|
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
|
|
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 `[`, 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	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
|
|