website/blog/releases/3.9/index.mdx
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.
import BrowserWindow from '@site/src/components/BrowserWindow';
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, that we now officially endorse and document on our release process.
This upgrade is further motivated by our dependencies:
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.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.
<BrowserWindow
url="http://localhost:3000/"
bodyStyle={{padding: 0, fontSize: 0}}>
<></>
</BrowserWindow>
:::tip 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.
:::
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:
export default {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
localeConfigs: {
en: {
// highlight-start
url: 'https://en.docusaurus.io',
baseUrl: '/',
// highlight-end
},
fr: {
// highlight-start
url: 'https://fr.docusaurus.io',
baseUrl: '/',
// highlight-end
},
},
},
};
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:
export default {
sidebar: [
{
type: 'category',
label: 'API',
// highlight-next-line
key: 'api-for-feature-1',
items: [],
},
{
type: 'category',
label: 'API',
// highlight-next-line
key: 'api-for-feature-2',
items: [],
},
],
};
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:
# highlight-next-line
layout: elk
---
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```
---
config:
layout: elk
---
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
Other notable changes include:
siteConfig.markdown.hooks.{onBrokenMarkdownLinks,onBrokenMarkdownImages} and deprecated siteConfig.onBrokenMarkdownLinks. The new callback hooks also let you recover from broken links/images by returning a fallback URL.siteConfig.markdown.emoji config option to disable the previously hard-coded remark-emoji behavior.@site/*, that we already supported for ES imports.useColorMode() hook when switching color modes, glitches that also affected your site's logo in the navbar.mailto: link (author.socials.email).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.