Docusaurus 3.9

We are happy to announce Docusaurus 3.9.

This release drops support for Node.js 18, adds support for Algolia DocSearch v4 with AskAI, improves i18n support, adds Mermaid ELK layout support, and comes with various other improvements and bug fixes.

Upgrading is easy. We follow Semantic Versioning, and minor version updates have no breaking changes, accordingly to our release process. Note that we consider dropping End-of-Life Node.js versions as non-breaking changes.

Dropping Node.js 18

In #11408, we have dropped support for Node.js 18, and the new minimum required Node.js version is now v20.0.

Although it may look like a runtime requirement breaking change, Node.js 18 reached End-of-Life. It won't receive security updates, and you shouldn't use it anymore. Dropping End-of-Life versions of Node.js on minor version releases is a common practice in the Node.js ecosystem (see for examples Astro 5.8), that we now officially endorse and document on our release process.

This upgrade is further motivated by our dependencies:

• Some of our dependencies now only receive security patches on newer versions that do not support Node.js 18 anymore. See, for example, this webpack-dev-server@4 security warning. To keep the Docusaurus v3 release line secure for our users, for both the runtime and third-party dependencies, the upgrade is necessary.
• Some of our dependencies are also dropping support for Node.js 18 in minor releases, transitively impacting Docusaurus runtime requirements. For example, Rspack 1.5 now requires Node.js 18.12, while Docusaurus v3 initially supported Node.js 18.0.

DocSearch v4

In #11327 and #11421, we added support for Algolia DocSearch v4. This new version comes with AskAI support, letting you add an AI-powered search assistant to your Docusaurus site that can answer questions based on what's in your documentation with a conversational experience.

http://localhost:3000/

DocSearch v4 is opt-in

Docusaurus v3 adds support for DocSearch v4 while keeping support for DocSearch v3.

Existing sites using DocSearch v3 can either stay on v3 or upgrade to v4 using their package manager (npm command: npm update @docsearch/react).

When using DocSearch v4, the new AskAI feature is not enabled by default: you also need to create an AskAI assistant and add it to the themeConfig.algolia.askAi config attribute.

i18n improvements

In #11316, we added new i18n.localeConfigs[locale].{url,baseUrl} config options to better support complex and multi-domain i18n deployments. Previously, Docusaurus relied on hard-coded heuristics that made sense for most i18n projects, but weren't flexible enough to accommodate all use cases, leading UX and SEO issues. It is now possible to configure each locale's deployment URL and base URL independently, overriding the default values inferred by Docusaurus:

docusaurus.config.js

export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
    localeConfigs: {
      en: {
        url: 'https://en.docusaurus.io',
        baseUrl: '/',
      },
      fr: {
        url: 'https://fr.docusaurus.io',
        baseUrl: '/',
      },
    },
  },
};

In #11304, we optimized our i18n infrastructure with a new i18n.localeConfigs[locale].translate flag that is now false by default for sites that do not use any translations. This leads to an improved dev experience and faster builds for non-i18n sites by avoiding unnecessary file system read attempts of the i18n directory.

In #11228, we added a new key attribute to the docs sidebar items, allowing to assign explicit translation keys to each sidebar item that use the same label and would otherwise lead to translation key conflicts:

sidebars.js

export default {
  sidebar: [
    {
      type: 'category',
      label: 'API',
      key: 'api-for-feature-1',
      items: [],
    },
    {
      type: 'category',
      label: 'API',
      key: 'api-for-feature-2',
      items: [],
    },
  ],
};

Mermaid ELK layouts

In #11357, we added support for Mermaid ELK layout algorithm, based on the Eclipse Layout Kernel (ELK). Compared to the default Dagre layout, it provides more sophisticated layout capabilities and configuration options, especially useful when working with large or intricate diagrams.

You can enable it by adding the extra @mermaid-js/layout-elk npm dependency, making it possible to use the layout: elk Mermaid diagram metadata:

```mermaid
---
config:
  layout: elk
---
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

Translations

• 🇧🇷 #11315: Add missing Brazilian Portuguese theme translations.
• 🇺🇦 #11305: Add missing Ukrainian theme translations.

其他改变：

Other notable changes include:

• In #11283, we added siteConfig.markdown.hooks.{onBrokenMarkdownLinks,onBrokenMarkdownLinks} and deprecated siteConfig.onBrokenMarkdownLinks. The new callback hooks also let you recover from broken links/images by returning a fallback URL.
• In #11282, we added the siteConfig.markdown.emoji config option to disable the previously hard-coded remark-emoji behavior.
• In #11397, we can now resolve site-aliased Markdown links starting with @site/*, that we already supported for ES imports.
• In #11294 and #11415, we upgraded to Rspack 1.5 and leveraging new Rspack config options to make Docusaurus build faster.
• In #11356, we improved the display of docs sidebar items with long labels.
• In #11405, we improved visual glitches caused by the useColorMode() hook when switching color modes, glitches that also affected your site's logo in the navbar.
• In #11383, we disabled a Docusaurus Faster HTML minifier optimization that prevents your site's social card from displaying properly on some social platforms (e.g., LinkedIn).
• In #11425, we added the ability for blog authors to display an email icon with a mailto: link (author.socials.email).
• In #11422, we removed the copy-text-to-clipboard in favor of the native navigator.clipboard API.

Check the 3.9.0 changelog entry for an exhaustive list of changes.