Skip to main content

Docusaurus 2.3

· 3 min read
Sébastien Lorber

We are happy to announce Docusaurus 2.3.

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

Docusaurus 2.2 social card

Highlights​

Google Tag Manager plugin​

Google Tag Manager is a tag management system that allows great flexibility. It enables analytics and marketing teams to easily load other third-party trackers and fire analytics tags.

We now have a @docusaurus/plugin-google-tag-manager package that you can use alongside or as an alternative to the existing gtag.js plugin (refer to this doc to understand when to use which solution).

Google is sunsetting Universal Analytics

Google will sunset its Universal Analytics on July 1, 2023, and ask users to migrate to Google Analytics 4.

Therefore, we are also deprecating our existing @docusaurus/plugin-google-analytics package. Docusaurus users should create a new Google Analytics 4 property, and migrate to the gtag.js plugin, or the Google Tag Manager plugin. Refer to the dedicated Docusaurus issue for details and questions.

Tabs Query String Support​

It is now possible to link a selected tab to a query string parameter. When a tab is selected, it will be stored in your browser URL as a ?qs-param=tab-value search parameter.

This feature allows deep-linking to a specific documentation tab that will pre-selected on page load.

When used alongside the groupId prop, the query string tab value takes precedence over the localStorage value.

Make sure to check the documentation and the demo below to understand how it works:

<Tabs groupId="current-os" queryString>
  <TabItem value="android" label="Android">
    Android
  </TabItem>
  <TabItem value="ios" label="iOS">
    iOS
  </TabItem>
</Tabs>
http://localhost:3000

Android

Nested admonitions​

It is now possible to nest one admonition within another by adding extra colons for the outer/enclosing admonition:

::::tip[nested admonitions]

You can now nest one admonition within another!

:::danger

Use this sparingly when it makes sense.

:::

::::
nested admonitions

You can now nest one admonition within another!

danger

Use this sparingly when it makes sense.

Blog createFeedItems​

A new blog plugin option feedOptions.createFeedItems gives you more control over the RSS/Atom feed generation. It is now possible to transform/filter/limit feed items through a new callback.

docusaurus.config.js
[
  '@docusaurus/preset-classic',
  {
    blog: {
      feedOptions: {
        createFeedItems: async (params) => {
          const {blogPosts, defaultCreateFeedItems, ...rest} = params;
          return defaultCreateFeedItems({
            // keep only the 10 most recent blog posts in the feed
            blogPosts: blogPosts.filter((item, index) => index < 10),
            ...rest,
          });
        },
      },
    },
  },
];

Translations​

We added or completed the default theme translation support for multiple languages:

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:

  • #8463 and #8328: fix some annoying Docusaurus layout issues
  • #8539: Algolia plugin options.searchPagePath should be correctly applied to search modal footer
  • #8462: Algolia plugin now makes it easier to transform displayed search results with custom logic
  • #8397: the deploy CLI now understands git url insteadOf config

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