npm / @docusaurus/core
@docusaurus/core
What changed in @docusaurus/core 2 to 3, from its official release notes, upgrade guides and advisories. Also covers @docusaurus/faster, @docusaurus/module-type-aliases, @docusaurus/preset-classic, @docusaurus/tsconfig, @docusaurus/types. Sources checked 2026-10-19.
8 breaking1 security9 new APIs and options1 performance4 behavior and defaults2 tooling20 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@docusaurus/core 330 changes
Breaking changes 1
Docusaurus v3 requires TypeScript v5.1 or later, so TypeScript users must upgrade their compiler when upgrading.
Security 1
Fixes a security issue in BaseUrlIssueBanner.
New APIs and options 5
Supports custom HTML elements in head tags.
Adds a flag for Git Eager VCS support through the experimental Faster configuration.
Adds a future v4 flag to disable MDX 1 compatibility by default.
Adds a future v4 flag for site storage namespacing.
Adds a siteConfig API for experimental VCS support.
Performance 1
Load the Mermaid library lazily.
Behavior and default changes 2
Docusaurus Faster is stable, and a v4 future flag turns it on by default.
Promotes siteConfig.storage to stable.
Tooling 1
TypeScript users are directed to replace the external @tsconfig/docusaurus package with the official @docusaurus/tsconfig package.
Fixes and other changes 19
Passes --host to server.listen() when running docusaurus serve.
Avoids transforming dotted directory links into assets.
Fixes edge cases in extractLeadingEmoji().
Preserves author names containing commas when parsing git log.
Accepts boolean attributes in headTags config validation.
HTTPS now supports non-RSA TLS certificates.
Uses the locale URL in the site config.
Removes redundant sidebar label titles.
Preserves lastmod when its timestamp is the epoch (0).
Fixed a webpackbar bug caused by a webpack breaking change.
Fix the validation logic for Algolia AskAI.
Improve Arabic theme translations.
Disable CSS counter minification.
Remove the Edit this page button from print view.
Allow i18n.localeConfigs.translate during validation.
Fix a bug that incorrectly required the Mermaid ELK layout dependency on v3.9.
Add missing Polish theme translations.
Fix CSS scroll-margin-top behavior when clicking footnote items.
Support the sidebar_key front matter attribute in docs.
@docusaurus/core 215 changes
Breaking changes 7
Versioned docs keep the original front matter id instead of changing it to include the version; Docusaurus sets the versioned ID internally.
MDX parses Markdown more strictly and fails builds on errors; HTML elements must be replaced by JSX elements.
MDX style attributes must use JSX style objects rather than HTML-style strings.
Use the <Translate> component with an id and description instead of the Docusaurus v1 <translate> component.
Versioned sidebar references use this format for versioned docs IDs instead of
version-${version}-${original_id}.Versioned docs use snapshots rather than fallback across versions, so each version must contain its own docs, including unchanged content.
Versioned sidebars must be populated for each version under the snapshot approach, rather than relying on another version's sidebar.
New APIs and options 4
Build a site for one locale at a time by passing a locale, such as fr.
Add --mdx to automatically convert Markdown content to MDX during migration.
Add --page to automatically migrate pages to v2.
Code translations are added at this path using Chrome i18n JSON format.
Behavior and default changes 2
Docusaurus 2 generates a single-page application and loads React in the browser, enabling more customizability.
Docusaurus 2 can be used to build websites beyond documentation sites, including blogs and product landing pages.
Tooling 1
A migration CLI handles many parts of migrating an existing Docusaurus 1 site to Docusaurus 2; some parts still require manual migration.
Fixes and other changes 1
Localized content is generally found under this path in Docusaurus v2.