Docusaurus 2.4

We are happy to announce Docusaurus 2.4.

The upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.

Highlights

Sidebar item description

In #8236, we made it possible to provide a new description attribute for docs sidebar items of type link and category.

sidebars.js

[
  {
    type: 'link',
    label: 'Link with description',
    href: 'https://docusaurus.io',
    description: 'Some link description',
  },
  {
    type: 'category',
    label: 'Category with description',
    description: 'Some category description',
    items: [],
  },
];

These descriptions will be used in category generated index pages.

Theme Query String

In #8708, we added the possibility to force Docusaurus to initialize itself in light or dark mode through a new docusaurus-theme query-string parameter.

This is useful to ensure a consistent theme when embedding an existing Docusaurus page into an iframe or WebView.

/docs/?docusaurus-theme=light

/docs/?docusaurus-theme=dark

Remark plugin npm2yarn upgrade

In #8690, we upgraded our Remark plugin @docusaurus/remark-plugin-npm2yarn with many conversion bug fixes, first-class support for pnpm, and the ability to register custom converters producing new tabs.

Run these commands!

```bash npm2yarn
npm install
npm run build
npm run myCustomScript -- --some-arg
```

http://localhost:3000

npm

npm install
npm run build
npm run myCustomScript -- --some-arg

Yarn

yarn install
yarn build
yarn myCustomScript --some-arg

pnpm

pnpm install
pnpm run build
pnpm run myCustomScript -- --some-arg

gtag support for multiple tracking IDs

In #8620 we added support for the @docusaurus/plugin-google-gtag plugin to declare multiple tracking IDs.

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        gtag: {
          trackingID: [
            'G-<YOUR-NEW-GA4-ID>',
            'UA-<YOUR-OLD-UA-ID>',
          ],
        },
      },
    ],
  ],
};

Google is sunsetting Universal Analytics

Google will sunset its Universal Analytics on July 1, 2023.

Docusaurus users should migrate to Google Analytics 4. Google does not permit to migrate your existing Universal Analytics data to your new Google Analytics 4 property.

To preserve the continuity of your analytics, we temporarily recommend that you report events to 2 tracking IDs at the same time: the old one (UA-*) and new one (G-*). Refer to the dedicated issue for details.

Developer Experience

In #8736, we improved how we render error messages and added initial support to render the full causal chain of an error (see ES2022 Error Cause).

tip

To see it in action, click here:

In #8735 we also made navbar-related error messages clearer to help users understand what they did wrong.

Translations

We made it possible to translate some new elements:

• #8677 introduces a new process.env.DOCUSAURUS_CURRENT_LOCALE (experimental) allowing you to localize your config file, including site title, tagline, announcement bar, baseUrl...
• #8616 allows to translate the navbar and footer logo alt text

We added default theme translation support for multiple languages:

• 🇭🇺 #8668: Hungarian
• 🇳🇴 #8631: Norwegian (Bokmål)

tip

Completing theme translations is an ongoing effort and an easy way to contribute to Docusaurus. We add new theme features regularly, for which we often need new translations.

Other changes

Other notable changes include:

• #8674: respect prefers-reduced-motion: reduce media query
• #8712: use a navbar item of type docSidebar in template
• #8801: allow tabs children to be falsy
• #8757: make search page react to external query-string changes
• #8803: fix code block buttons position in RTL
• #8615: fix color mode toggle when using dark navbar
• #8699: fix navbar dropdown tab focus bug

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