npm / @astrojs/markdoc

@astrojs/markdoc

What changed in @astrojs/markdoc 1 to 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-20.

7 breaking1 new APIs and options6 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@astrojs/markdoc 28 changes

Image handling is updated for Astro 7.4 and requires astro@^7.4.0.
2.1.0release notes
The minimum supported Node.js version is now 22.22.0.
2.1.0release notes

YAML parsing now supports timestamps and merge keys in Markdoc.
2.0.10release notes

YAML errors are now formatted consistently across Astro, Markdown, MDX, and Markdoc.
2.0.10release notes
User-written transforms are preserved when a tag or node also specifies a custom render component; only Markdoc’s built-in transforms are removed.
2.0.5release notes
Custom transforms are no longer dropped for tag and node names requiring bracket access; detection recognizes bracket notation, optional chaining and whitespace.
2.0.5release notes
Corrects the dependencies listed in the peerDependencies field.
2.0.2release notes
Fixes a crash when rendering Shiki-highlighted code blocks inside list items.
2.0.1release notes

Temporary support for Node >=20.19.1 was removed because Stackblitz now uses Node 22 by default.
1.0.2release notes
Updates the Astro peer dependency to 6.0.0, affecting which Astro version is compatible with @astrojs/markdoc.
1.0.1release notes
Markdown heading ID generation is updated, which may change the IDs generated for headings.
1.0.0release notes
When a Markdoc node config specifies both render and transform, render now takes precedence over transform.
1.0.0release notes
Astro v6 upgrades to Vite v7.0 for the development server and production bundler.
1.0.0release notes

Custom attribute declarations are synced between same-named table tags and nodes, so defining them on either side avoids validation errors.
1.0.0release notes