v1.5 To v1.6

v1.6.0 is a stabilization release. It does not change stored content or Payload schema fields, so no database migration is required. Normal rendered output for valid Markdown is unchanged.

Requirements

Node.js >=20.9.0. Shiki 4 and Next.js 16 already required it; the package metadata now says so.

Directive Parsing

A directive now opens only when the source line itself starts with the marker (:::name or ::button / ::badge). Text that merely looks like a marker is prose:

A paragraph that starts with inline code, emphasis or a link, such as `:::toc` links to the same IDs, no longer opens a directive. Earlier releases could silently swallow or delete the rest of the page.
Words after a marker that are not key=value, #id or .class (for example :::callout this is my title) produce an "Unexpected text" diagnostic and the line stays text. Put the title in a label or attribute instead: :::callout[This is my title] or :::callout{title="This is my title"}.
A ::: / :: marker inside a list item, blockquote or table now produces a warning instead of rendering as literal text with no message.

The editor linter uses the same scanner as the renderer, so the admin field shows the same diagnostics the renderer reports.

Links And Raw HTML

href values on :::card, :::cards, ::button and ::badge are checked against the same protocol allowlist as Markdown links. javascript: and similar URLs are dropped and reported.
Raw HTML can no longer imitate directive markup (data-vl-layout, data-href, icon markers and similar internal attributes are removed from authored HTML).
id and name attributes written in raw HTML get the user-content- prefix, which prevents DOM clobbering. Link to an anchor you wrote in raw HTML as #user-content-<id>. Generated heading, footnote and tab ids are unchanged.

Icons

Icon SVG files are parsed and filtered through a strict allowlist instead of regular expressions. Scripts, event handlers, external references and foreign content are removed. <style> blocks are no longer inlined into the page (they applied to the whole document). Instead, class rules in an icon's own <style> block have their safe presentation declarations (fill, stroke, stroke line settings, opacity, gradient stops, fill and clip rules, basic text settings) applied to the matching elements of that icon. Font Awesome duotone icons (.fa-secondary{opacity:.4}) and Illustrator, Figma or Sketch exports (.cls-1{fill:#0a84ff;stroke-miterlimit:10}) therefore look the same. Values that could load or reference anything (url(), var(), calc(), escapes) are dropped.

Ids And Anchors

Heading ids are unique even when a generated suffix collides with a real heading (Foo, Foo, Foo 1 no longer produce two foo-1 ids). Non-colliding ids are unchanged.
Tab labels without ASCII letters (for example 日本語) get tab-1, tab-2, … values instead of all colliding on default.
A second tabs block with the same tab names in one document gets suffixed ids.
slugifyHeading, createHeadingSlugger and extractHeadingAnchors are exported from @valkyrianlabs/payload-markdown/advanced so other tools can compute the same anchors.

Code Blocks

An invalid code.shikiTheme or an unknown entry in code.langs falls back with a warning instead of making every page with a code block render "Failed to render markdown."
Highlighting is deterministic under load. Earlier releases could render a code line partly unhighlighted when the server was busy (Shiki's per-line time budget ran out during the first tokenization).
Fence languages match case-insensitively and by alias (JS, TypeScript). A fence whose language is not loaded renders as plain text, as before, and now reports a diagnostic. Add the language to code.langs to highlight it.

Rendering API

errorFallback is shown only when rendering fails, not for warnings. Render results carry errors next to warnings.
New CSS-free entry point @valkyrianlabs/payload-markdown/render exports renderMarkdown() (HTML plus headings, positioned diagnostics, plain text and links) and compileMarkdown(). It works in plain Node without a bundler.
@valkyrianlabs/payload-markdown/client now exports the client components, and @valkyrianlabs/payload-markdown/styles.css exports the stylesheet. Existing import paths, including @valkyrianlabs/payload-markdown/server#PayloadMarkdownField in import maps, keep working.
A generated directive specification ships as @valkyrianlabs/payload-markdown/directive-spec.json and through getDirectiveSpec() from /render.

Plugin Settings

Plugin settings are shared by every installed copy of the package in a process. If two different versions are installed, a single warning names both versions. Install one version (packages that build on this one, such as payload-markdown-docs, list it as a peer dependency).
payloadMarkdown({ enabled: false }) clears previously registered settings, and the plugin no longer mutates the collection objects you pass in.

Markdown Field

The field accepts up to 1,000,000 characters by default (Payload text fields default to 40,000). Set maxLength on markdownField() to change it. This is validation only; no schema change.
The field shows Payload's label, required marker, description and validation errors, and respects read-only access.

Per-Block Params

The markdown block's Markdown Blocks Params are now applied. Earlier releases stored them but never used them when rendering. When Enable Blocks Params is checked, a block's set values override the global and collection block settings for that block, and empty values inherit them. Checking the box fills the fields with the block's current effective values, so enabling it changes nothing until a field is edited. No schema change; blocks whose params were never enabled render as before.

Run payload generate:importmap after upgrading: the checkbox uses a new admin component (@valkyrianlabs/payload-markdown/client#MarkdownBlockParamsEnableField). See Fields And Blocks.

Editor Themes

The admin editor receives your configured directive themes and icon packs, so custom themes no longer show "Unknown theme" warnings and icon references complete in the editor.