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