This will be the last release in the v3.x line, and it helps you prepare for Docusaurus v4.

Upgrading is easy. We follow Semantic Versioning, and minor version updates have no breaking changes, according to our release process.

However, if you opt in for upcoming Docusaurus v4 breaking changes globally with future.v4: true, make sure to review the dedicated section below.

v4 Future Flags​

The Docusaurus v4 Future Flags let you opt in for upcoming Docusaurus v4 breaking changes incrementally and prepare for Docusaurus v4 ahead of time. You can enable them all at once with future.v4: true.

This release introduces new flags and breaking changes that might break your site if you use future.v4: true and upgrade:

• future.v4.siteStorageNamespacing: In Docusaurus v4, localStorage keys will be automatically namespaced by default (theme => theme-<hash>) to prevent key conflicts. This is likely to reset your site's visitor storage unless you migrate it to new key names. See the dedicated Site Storage section below.
• future.v4.fasterByDefault: Docusaurus Faster is now stable and will be enabled by default in Docusaurus v4. See the dedicated Docusaurus Faster section below.
• future.v4.mdx1CompatDisabledByDefault: In Docusaurus v4, MDX v1 compatibility options will be disabled by default, and you might have to adjust your docs accordingly. See the dedicated Strict MDX section below.

Security​

npm supply chain attacks have surged recently. A single compromised maintainer or package can ripple through the ecosystem and affect thousands of downstream users, as seen with the axios compromise.

We’ve taken steps to strengthen our supply chain, and recommend securing your own site with additional measures as well.

Trusted Publishing​

We adopted npm Trusted Publishing for stable and canary releases.

Releases are now published through a single publish.yml GitHub Actions workflow using short-lived OIDC tokens. Each release has verifiable provenance, with a transparency log showing how and when it was published.

Security Workflow​

In #11874, we introduced a new security workflow that runs daily and on every pull request. It scans for suspicious dependency updates affecting our official packages and their transitive dependencies:

• Install the Docusaurus site template through the Socket Firewall to detect known malware in our dependency graph
• Check for unexpected preinstall and postinstall lifecycle scripts, using pnpm strictDepBuilds
• Check for GitHub repository and tarball URL dependencies, using pnpm blockExoticSubdeps
• Check for packages that downgrade their trust level, using pnpm trustPolicy: no-downgrade
• Run similar checks on our own monorepo, to protect Docusaurus maintainers and contributors

Secure Your Site​

Read the npm security best practices guide to learn how to secure your site — and npm applications in general — from compromised dependencies.

Each package manager offers different security options. In our experience, pnpm offers the best ones. We won't document all the possibilities, but here's a pnpm config example that should work well with Docusaurus:

minimumReleaseAge: 10080

blockExoticSubdeps: true

strictDepBuilds: true
allowBuilds:
  '@swc/core': true
  core-js-pure: true
  core-js: true

trustPolicy: no-downgrade
trustPolicyExclude:
  - 'detect-port@1.6.1'
  - 'semver@6.3.1'

# npm v11.10+ - .npmrc
min-release-age=7

# pnpm v10.16+ - pnpm-workspace.yaml
minimumReleaseAge: 10080

# Yarn v4.10+ - .yarnrc.yml
npmMinimalAgeGate: "7d"

# Bun v1.3+ - bunfig.toml
[install]
minimumReleaseAge = 604800

Docusaurus Faster - Stable​

Docusaurus Faster lets you opt in for our modernized build infrastructure. This includes Rspack, SWC, LightningCSS, and other optimizations.

This release improves Docusaurus Faster with a new gitEagerVcs flag and full support for Yarn PnP.

In #11802, we marked Docusaurus Faster as stable. You now need to update your config accordingly:

const config = {
  future: {
-   experimental_faster: true,
+   faster: true,
  },
};

Site Storage - Stable​

In #11797, we marked the config.storage API as stable. You now need to update your config accordingly:

 const config = {
+  storage: {
+    type: 'localStorage',
+    namespace: true,
+  },
-  future: {
-    experimental_storage: {
-      type: 'localStorage',
-      namespace: true,
-    },
-  },
 };

Strict MDX​

This release introduces new MDX options to encourage stricter usage of native MDX syntax, instead of relying on proprietary Docusaurus syntax on top of MDX.

Historically, Docusaurus compiled your files with MDX v1, which was quite forgiving. Since then, the ecosystem has widely moved to MDX v3, which is stricter. Docusaurus v3.0 introduced markdown.mdx1Compat to help you upgrade incrementally.

In Docusaurus v4, we plan to turn the markdown.mdx1Compat options off by default. This upcoming change is now part of our v4 future flags (future.v4.mdx1CompatDisabledByDefault: true).

We'd like the community to adopt a stricter, native MDX syntax for a few reasons:

• This makes your docs more portable: external tools like Prettier, ESLint, TypeScript, VS Code, and GitHub can understand them.
• Docusaurus doesn't need to pre-process your documents with regular expressions before MDX compilation.
• This improves compatibility with the Unified ecosystem (Remark, MDX) and the MDX Playground.

Strict Extensions​

We believe that:

• .md should be parsed as CommonMark
• .mdx should be parsed as MDX

In reality, Docusaurus has only ever supported MDX, and we should have used the .mdx extension from the start. Newly initialized sites now use .mdx by default (#11897). We encourage you to rename your existing files to .mdx as well, so that external tools can understand your content is MDX.

Strict Admonitions​

We have historically supported admonitions with titles using the :::type My Title syntax. Although convenient, this is a proprietary Docusaurus syntax.

The Markdown Directive syntax is more generic and reusable. It is not yet standardized, but widely adopted across ecosystems, including through the remark-directive package. We encourage you to migrate your admonitions to the :::type[My Title] syntax:

-:::warning Pay Attention
+:::warning[Pay Attention]

 Content

 :::

Strict Comments​

MDX v3 does not support HTML comments <!-- comment -->, but supports JSX comment expressions {/* comment */}.

If you use HTML comments, we encourage you to migrate to JSX comments. For example, you can truncate blog posts with a JSX comment:

 # My Blog Post

-<!-- truncate -->
+{/* truncate */}

 blog post content

Strict Heading IDs​

Our historical heading IDs syntax {#my-id} is also a proprietary Docusaurus syntax, leading to ecosystem incompatibilities.

In #11755, we introduced a new heading ID syntax based on native MDX comments that we encourage you to adopt:

-## My Heading {#my-id}
+## My Heading {/* #my-id */}

In #11777, we also added an option to our write-heading-ids CLI to emit and migrate to the new syntax:

docusaurus write-heading-ids --syntax mdx-comment --migrate

VCS API - Experimental​

In #11512, we added a new experimental VCS (Version Control System) API, and implemented built-in performance improvements when reading from the Git history.

Historically, Docusaurus only integrated with Git, reading the commit history to implement features such as:

• Displaying the last update date/time in the docs, blog and pages plugin when using the showLastUpdateAuthor or showLastUpdateTime options
• Displaying the blog creation date in the blog plugin
• Computing the <lastmod> value in the sitemap plugin

This new API makes it possible to integrate Docusaurus with other VCS, such as SVN, Mercurial, a CMS or any other external system.

Here's an example implementation using hardcoded data:

export default {
  future: {
    experimental_vcs: {
      initialize: ({siteDir}) => {
        // You can initialize and cache VCS data here, if needed
      },
      getFileCreationInfo: async (filePath: string) => {
        return {timestamp: 1490997600000, author: 'Slash'};
      },
      getFileLastUpdateInfo: async (filePath: string) => {
        return {timestamp: 1490997600000, author: 'Slash'};
      },
    },
  },
};

We have also noticed that our historical strategy to read from the Git history can be a significant build performance bottleneck for large Docusaurus sites. Issuing one git log <filepath> call per MDX file doesn't scale well.

To solve this bottleneck, we implemented a strategy that reads the whole Git repository eagerly in a single git log call, leading to significant performance improvements. This strategy is now part of Docusaurus Faster (future.faster.gitEagerVcs: true) and will become the default in Docusaurus v4.

We also provide built-in VCS preset strategies. The available presets are:

• git-ad-hoc: the historical strategy based on git log <filename> calls
• git-eager: the new Git strategy that reads your whole repository upfront
• hardcoded: returns a hardcoded value, useful in dev/tests to speed up DX
• disabled: returns null for all files, considering them untracked
• default-v1: the historical default (dynamic, git-ad-hoc in prod, hardcoded in dev)
• default-v2: the upcoming Docusaurus v4 default (dynamic, git-eager in prod, hardcoded in dev)

export default {
  future: {
    experimental_vcs: 'default-v2',
  },
};

Traductions​

• 🇵🇰 #11632: Add new Urdu ur theme translations.
• 🇧🇷 #11533: Complete missing Brazilian Portuguese pt-BR theme translations.

Autres modifications​

Voici les autres changements notables :

• In #11843, we now use TypeScript 6.0 for newly initialized sites. However, it requires "ignoreDeprecations": "6.0" for now.
• In #11571, the siteConfig.headTags API now accepts custom HTML elements.
• In #11675, the live code block theme now has a button to reset the playground.
• In #11734, we split the <DocCard> component to make it easier to extend/swizzle. It's now easier to assign custom emojis for the docs generated index page.
• In #11733, the <Tabs> component now uses React context instead of props, making it possible to create custom <TabItem> components.
• In #11696, all newly initialized TypeScript sites will have "strict: true" by default.
• In #11611, we made it possible to create a new Docusaurus site in ., the current directory.
• In #11666, the pages plugin can now use Markdown file path links ([text](./other-page.md)), as the docs and blog plugins already support it.
• In #11642, admonitions now support class/id shortcuts, such as :::note{.my-class #my-id}.
• In #11541 and #11683, we made sure Docusaurus is compatible with the latest version of Algolia DocSearch 4.x, unlocking new features such as AskAI Suggested Questions.
• In #11684 and #11653, we removed many third-party dependencies from our create-docusaurus CLI, making it faster to create a new site.
• In #11794, we fixed a long-standing bug that prevented the translation of category index page titles in pagination links.
• In #11784, we changed the syntax we recommend for math equations, preferring regular Markdown code blocks over $$ to improve docs portability.
• In #11753, we added a basic AGENTS.md file. As a reminder, any AI usage in Docusaurus contributions must be disclosed.
• In #11698, we upgraded our monorepo to React 19. We'll drop support for React 18 in Docusaurus v4.

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

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, 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/

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:

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:

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
```

Traductions​

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

Autres modifications​

Voici les autres changements notables :

• In #11283, we added 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.
• 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.

This release improves build performance, includes new features and introduces "Future Flags" to prepare your site for Docusaurus 4.

Upgrading is easy. We follow Semantic Versioning, and minor version updates have no breaking changes, accordingly to our release process.

Performance​

This release keeps improving our build infrastructure performance with various optimizations, and 2 new Docusaurus Faster options.

Docusaurus Faster​

Docusaurus Faster has been introduced in Docusaurus v3.6, and permits you to opt-in for our upgraded build infrastructure and helps you build your site much faster. The experimental flags can be turned on individually, but we recommend to turn them all at once with this convenient shortcut:

const config = {
  future: {
    experimental_faster: true,
  },
};

Persistent Cache​

In #10931, we have enabled the Rspack persistent cache. Similarly to the Webpack persistent cache (already supported), it permits to greatly speed up the bundling of the Docusaurus app on subsequent builds.

In practice, your site should build much faster if you run docusaurus build a second time.

This feature depends on using the Rspack bundler, and can be turned on with the rspackPersistentCache flag:

const config = {
  future: {
    experimental_faster: {
      rspackBundler: true, // required flag
      rspackPersistentCache: true, // new flag
    },
  },
};

Result: On average, you can expect your site's bundling time to be ~2-5× faster on rebuilds 🔥. The impact can be even more significant if you disable the optional concatenateModule optimization.

Worker Threads​

In #10826, we introduced a Node.js Worker Thread pool to run the static side generation code. With this new strategy, we can better leverage all the available CPUs, reduce static site generation time, and contain potential memory leaks.

This feature can be turned on with the ssgWorkerThreads flag, and requires the v4.removeLegacyPostBuildHeadAttribute Future Flag to be turned on:

const config = {
  future: {
    v4: {
      removeLegacyPostBuildHeadAttribute: true, // required
    },
    experimental_faster: {
      ssgWorkerThreads: true,
    },
  },
};

Result: On average, you can expect your site's static site generation time to be ~2× times faster 🔥. This was measured on a MacBook Pro M3 and result may vary depending on your CI.

Other Optimizations​

We identified and resolved several major bottlenecks, including:

• In #11007, we optimized the dev server startup time for macOS users. We figured out that the code to open your browser used expensive synchronous/blocking calls that prevented the bundler from doing its work. From now on, the bundler and the macOS browser opening will run in parallel, leading to a faster docusaurus start experience for all macOS users.
• In #11163, we noticed that the docs showLastUpdateAuthor and showLastUpdateTime are quite expensive, and require to run a git log command for each document. On large sites, running these commands in parallel can exhaust the system and lead to Node.js EBADF errors. We implemented a Git command queue to avoid exhausting the system, which also slightly increased performance of our plugin's loadContent() lifecycle.
• In #10885, we implemented an SVG sprite for the external link icon. Due to its repeated appearance in various places of your site (navbar, footer, sidebars...), using a React SVG component lead to duplicated SVG markup in the final HTML. Using a sprite permits to only embed the icon SVG once, reducing the generated HTML size and the static generation time. We plan to use more SVG sprites in the future.
• In #11176, we fine-tuned the webpack/Rspack configuration to remove useless optimizations.

Impact​

We have upgraded the React Native website to Docusaurus v3.8 already. Here's an updated benchmark showing the global Docusaurus Faster impact on total build time for a site with ~2000 pages:

We measured similar results on our website:

You can also expect memory usage improvements, and a faster docusaurus start experience.

Future Flags​

The Docusaurus v4 Future Flags let you opt-in for upcoming Docusaurus v4 breaking changes, and help you manage them incrementally, one at a time. Enabling all the future flags will make your site easier to upgrade to Docusaurus v4 when it's released.

const config = {
  future: {
    v4: true,
  },
};

CSS Cascade Layers​

In Docusaurus v4, we plan to leverage CSS Cascade Layers. This modern CSS feature is widely supported and permits to group CSS rules in layers of specificity. It is particularly useful to give you more control over the CSS cascade. It makes the CSS rules less dependent on their insertion order. Your un-layered rules will now always override the layered CSS we provide.

In #11142, we implemented a new experimental @docusaurus/plugin-css-cascade-layers that you can turn on through the v4.useCssCascadeLayers flag if you use the classic preset:

export default {
  future: {
    v4: {
      useCssCascadeLayers: true,
    },
  },
};

We consider this feature as a breaking change because it can slightly alter the CSS rules application order in customized sites. These issues are usually limited, and relatively easy to fix (see for example the React Native CSS changes). Sites that do not provide custom CSS and do not swizzle any component should not be affected.

In practice, it permits to automatically apply built-in CSS Cascade Layers to all the CSS we provide, including our opinionated CSS framework Infima:

@layer docusaurus.infima {
  h1 {
    /* Infima css rules */
  }
  pre {
    /* Infima css rules */
  }
}

Layers can help solves our long-standing Global CSS pollution issue. Our built-in global CSS rules may conflict with yours, making it harder to use Docusaurus to create playgrounds, demos and embedded widgets that are isolated from our CSS. Thankfully, CSS Cascade Layers can be reverted to create HTML subtrees that are not affected by the CSS Docusaurus provides.

/* The "impossible" :not() selector helps increase the specificity */
.my-playground:not(#a#b) {
  &,
  * {
    @layer docusaurus.infima {
      all: revert-layer;
    }
  }
}

postBuild() Change​

In #10850, we added a new removeLegacyPostBuildHeadAttribute Future Flag that slightly changes the signature of the postBuild() plugin lifecycle method, removing the head attribute.

export default {
  future: {
    v4: {
      removeLegacyPostBuildHeadAttribute: true,
    },
  },
};

This legacy data structure is coming from our react-helmet-async dependency and should have never been exposed as public API in the first place. It is not serializable, which prevents us from implementing Worker Threads for the static site generation.

While technically a breaking change, we believe this change will not affect anyone. We couldn't find any open source plugin that uses the head parameter that this method receives. If turning this flag on breaks your site, please let us know here.

System Color Mode​

In #10987, the classic theme now lets you revert the color mode to the system/OS value.

Code Block Refactor​

In #11058, #11059, #11062 and #11077, the theme code block components have been significantly refactored in a way that should be much easier to swizzle and extend.

According to our release process, this is not a breaking change, but sites that have swizzled these components may need to upgrade them.

Traductions​

• 🇹🇷 #10893: Add missing Turkish theme translations.
• 🇵🇱 #10884: Add missing Polish theme translations.
• 🇨🇳 #10816: Add missing Chinese theme translations.
• 🇯🇵 #11030: Add missing Japanese theme translations.

Maintenance​

Docusaurus 3.8 is ready for Node.js 24 and TypeScript 5.8.

We also removed useless npm packages and internalizing unmaintained ones:

• In #11010 and #11014, we internalized the unmaintained react-ideal-image and react-waypoint package used in @docusaurus/plugin-ideal-image, and made them compatible with React 19.
• In #10956, we removed our dependency to the unmaintained react-dev-utils package (from Create-React-App).
• In #10358, we replaced the unmaintained shelljs package by execa
• In #11138, we removed the reading-time package in favor of the built-in Intl.Segmenter standard API to compute blog post reading times.
• In #11037, we removed the useless clean-webpack-plugin.

Autres modifications​

Voici les autres changements notables :

• In #10852, the theme docsVersionDropdown navbar item now accepts a versions attribute.
• In #10953, the @docusaurus/remark-plugin-npm2yarn plugin now supports Bun tabs conversions by default.
• In #10945, more stable CSS classes are now applied to the main theme layout elements, to let you create more reliable CSS selectors.
• In #10846, the Markdown code block showLineNumbers metastring can now accept a number to initialize the line counter initial value.
• In #11090, we made it easier to provide a custom page title formatter.
• In #11088, the page plugin now supports frontMatter.slug like docs and blog plugins already do.
• In #10875, the docs versioning CLI now also copies localized docs JSON translation files.

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

Docusaurus is now compatible with React 19.

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

Highlight​

React 19​

In #10763, we added support for React 19, and the Docusaurus website is running on React 19 already.

From now on, all newly initialized sites will run on React 19 by default, and React 19 will be the minimum required version Docusaurus v4.

However, React 18 remains supported, and existing Docusaurus sites can either choose to stay on React 18, or upgrade their dependencies to React 19:

{
  "name": "my-docusaurus-site",
  "dependencies": {
-   "react": "^18.0.0",
-   "react-dom": "^18.0.0"
+   "react": "^19.0.0",
+   "react-dom": "^19.0.0"
  }
}

Along the way, we fixed all the remaining hydration errors reported by React 19, some of them produced by our aggressive HTML minifier settings.

SVGR plugin​

Docusaurus has built-in support for SVGR, allowing you to seamlessly import and use SVG files as React components:

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;

This built-in support has been the source of various bug reports due to the inability to customize the SVGR Options, in particular the SVG Optimizer options.

In #10677, we extracted a new @docusaurus/plugin-svgr that you can now configure according to your needs. It is included by default in our classic preset:

export default {
  presets: [
    [
      'classic',
      {
        svgr: {
          svgrConfig: {
            // Your SVGR options ...
            svgoConfig: {
              // Your SVGO options ...
              // Use "svgoConfig: undefined" to use a svgo.config.js file
            },
          },
        },
      },
    ],
  ],
};

Autres modifications​

Voici les autres changements notables :

• #10768: Blog authors have built-in icons for social platforms bluesky, mastodon, threads, twitch, youtube, instagram.
• #10729: Blog now supports frontMatter.sidebar_label
• #10803: @docusaurus/remark-plugin-npm2yarn now supports Bun conversions.
• #10672: Upgrade Algolia DocSearch to algoliasearch v5.
• #10800: Docusaurus Faster turns Rspack incremental mode on by default.
• #10783: Improve Dutch theme translations.
• #10760: Improve Korean theme translations.

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

Docusaurus is now ⚡️⚡️⚡️ much faster to build your site.

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

Points importants​

This release has been mostly focused on build performance through the Docusaurus Faster project.

Docusaurus Faster​

The Docusaurus Faster project's goal is to reduce the build times and memory consumption.

We have worked on multiple optimizations and modernized our infrastructure to use faster Rust-based tools, notably:

• 🦀 Rspack: Fast Rust-based web bundler, almost drop-in replacement for webpack
• 🦀 SWC: Speedy Web Compiler, Rust-based platform for the Web (HTML, CSS, JS)
• 🦀 Lightning CSS: An extremely fast CSS parser, transformer, bundler, and minifier

Impacts​

Adopting a new infrastructure can have various impacts. It's impossible to list them all exhaustively, so let's focus on the major ones.

To help you adopt it easily, we have been fairly conservative in terms of expected static site output and browser support.

Build Time​

Benchmarks on community site show that you can expect your production site to build ⚡️2 to 4 times faster! 🔥:

• React Native website: 3.04x faster 🔥
• Babel website: 3.27x faster 🔥
• Lexical website: 2x faster 🔥

How to benchmark

Memory Consumption​

You should also notice an improvement in memory consumption:

• The new infrastructure consumes less memory overall
• We fixed an important memory leak that affects in particular i18n sites
• We added CI checks to ensure that we don't regress, and that our site and init template can both build in a memory-constrained environments
• We added internal tooling to better understand which step of a build consumes memory
• We removed a process.exit(0) that can hide memory leaks in your own code and third-party plugins

Other Impacts​

• The HTML minifier now emits warnings in case of invalid HTML markup
• The static HTML output is ~5% smaller
• Some bugs are automatically fixed by the new infrastructure

Adoption Strategy​

This new infrastructure is a breaking change, but it is opt-in and does not require a new major version of Docusaurus.

Before using Docusaurus Faster, add this new package:

npm install @docusaurus/faster

yarn add @docusaurus/faster

pnpm add @docusaurus/faster

bun add @docusaurus/faster

To help you adopt it incrementally under Docusaurus v3, we're introducing a set of feature flags that you can activate progressively.

We recommend turning them on all at once with this simple boolean shortcut:

const config = {
  future: {
    experimental_faster: true,
  },
};

In case one of the flags does not work for your site, it's possible to turn feature flags on independently:

const config = {
  future: {
    experimental_faster: {
      swcJsLoader: true,
      swcJsMinimizer: true,
      swcHtmlMinimizer: true,
      lightningCssMinimizer: true,
      rspackBundler: true,
      mdxCrossCompilerCache: true,
    },
  },
};

• swcJsLoader: Use SWC to transpile JS (instead of Babel)
• swcJsMinimizer: Use SWC to minify JS (instead of Terser)
• swcHtmlMinimizer : Use SWC to minify HTML and inlined JS/CSS (instead of html-minifier-terser)
• lightningCssMinimizer: Use Lightning CSS to minify CSS (instead of cssnano and clean-css)
• rspackBundler: Use Rspack to bundle your app (instead of webpack)
• mdxCrossCompilerCache: Compile MDX files once for both browser/Node.js environments instead of twice

Plugins​

The new infrastructure uses Rspack. By chance, Rspack is almost 100% compatible with webpack, and Rspack shouldn't break our plugin ecosystem.

Most Docusaurus plugins should work out of the box with Rspack, even those implementing configureWebpack.

However, some of them will require small modifications to make them compatible with Rspack. The general idea is to avoid importing webpack directly, and use the "dynamically provided" webpack instance instead:

-import webpack from 'webpack';

export default function (context, options) {
  return {
    name: 'custom-docusaurus-plugin',
-   configureWebpack(config, isServer) {
+   configureWebpack(config, isServer, {currentBundler}) {
      return {
        plugins: [
-         new webpack.DefinePlugin({}),
+         new currentBundler.instance.DefinePlugin({}),
        ]
      };
    },
  };
}

Next Steps​

It's only the beginning: we will continue working on the Docusaurus Faster project and already have a few more performance improvements planned.

Depending on your feedback, we plan to make this new infrastructure the default in an upcoming major version of Docusaurus.

🙏 We'd like to thank the authors of all these great tools that already helped us make Docusaurus much faster than before. In particular the Rspack team that supported us along the way, handled our feedback very quickly and implemented all the missing features we needed to make it happen. 👏

Rsdoctor plugin​

In #10588, we created a Docusaurus plugin for Rsdoctor. It analyzes the bundling phase of Docusaurus and helps you figure out what slows down the bundler in terms of loaders, plugins and minimizers. It works for both webpack and Rspack.

To use it, install the new @docusaurus/plugin-rsdoctor package, and then use the plugin in your config:

export default {
  plugins: [
    [
      'rsdoctor',
      {
        /* options */
      },
    ],
  ],
};

export default {
  plugins: [
    process.env.RSDOCTOR === 'true' && [
      'rsdoctor',
      {
        /* options */
      },
    ],
  ],
};

# Build without Rsdoctor
npm run build

# Build with Rsdoctor
RSDOCTOR=true npm run build

Mermaid​

In #10510, we relaxed our Mermaid diagrams dependency range to allow newer major versions of Mermaid. We now support both Mermaid 10/11, and expect upcoming versions to be compatible, letting you upgrade on your own terms.

This unlocks new types of diagrams, such as Architecture Diagrams:

Traductions​

• 🇸🇮 #10551: Improve Slovenian theme translations.
• 🇻🇳 #10507: Improve Vietnamese theme translations.
• 🇪🇸 #10413: Improve Spanish theme translations.

Autres modifications​

Voici les autres changements notables :

• #10586: Blog support for frontMatter.title_meta to override frontMatter.title for SEO reason.
• #10600: docusaurus build and docusaurus deploy now support multiple --locale CLI args.
• #10454: docusaurus-remark-plugin-npm2yarn upgrades to npm-to-yarn v3 and can convert npx commands.
• #10612: Canary releases will use 3.5.2-canary-<number> instead of 0.0.0-canary-<number> to respect plugins peerDependency constraints.
• #10547: @docusaurus/tsconfig upgrades to target: 'es2022'.
• #10514: Remove babel.config.js from Docusaurus init templates to discourage customizing Babel.

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

This release contains many new exciting blog features.

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

Points importants​

Blog Social Icons​

In #10222, we added the possibility to associate social links to blog authors, for inline authors declared in front matter or global through the authors.yml file.

slorber:
  name: Sébastien Lorber
  # other author properties...
  socials:
    x: sebastienlorber
    linkedin: sebastienlorber
    github: slorber
    newsletter: https://thisweekinreact.com

Icons and handle shortcuts are provided for pre-defined platforms x, linkedin, github and stackoverflow. It's possible to provide any additional platform entry (like newsletter in the example above) with a full URL.

Blog Authors Pages​

In #10216, we added the possibility for global blog authors (declared in authors.yml) to have their own dedicated page listing all the blog posts they contributed to.

This feature is opt-in and mostly relevant for multi-author blogs. You can turn it on for a specific author by setting the page: true property:

slorber:
  name: Sébastien Lorber
  # the description will be displayed on the author's page
  description: 'A freelance React and React-Native developer...'
  page: true # Turns the feature on

This creates a dedicated author page at /blog/authors/slorber.

An authors index page is also created, listing all the blog authors.

Check the blog authors pages guide for details.

Blog Feeds Styling​

In #9252, we added support for styling your blog feeds by providing custom XSLT .xls files for the RSS and Atom feeds. This allows browsers to render the feeds in a more visually appealing way, like a regular HTML page, instead of the default XML view.

const blogOptions = {
  feedOptions: {
    xslt: {
      rss: 'custom-rss.xsl',
      atom: 'custom-atom.xsl',
    },
  },
};

Writing your own XSLT can be complex, but you can also use xslt: true to turn on the built-in style:

const blogOptions = {
  feedOptions: {
    xslt: true,
  },
};

Blog Sidebar Grouping​

In #10252, we added support for grouping blog posts by years in the blog sidebar.

This feature is now turned on by default, but can be disabled with themeConfig.blog.sidebar.groupByYear: false.

Blog Consistency Options​

We added new blog options to enforce recommended practices for your blog posts:

onInlineAuthors​

We believe large multi-blogs are easier to manage by using global authors, declared in authors.yml. This notably permits to avoids duplicating author information across multiple blog posts, and now permits to generate author pages.

In #10224, we added the onInlineAuthors option. Use onInlineAuthors: 'throw' to forbid inline authors, and enforce a consistent usage of global authors.

onUntruncatedBlogPosts​

We believe blog posts are better using truncation markers (<!-- truncate --> or {/* truncate */}). On paginated lists (blog home, tags pages, authors pages), this permits to render a more concise preview of the blog post instead of a full blog post.

In #10375, we added the onUntruncatedBlogPosts option. Use onUntruncatedBlogPosts: 'throw' to enforce a consistent usage of truncation markers.

Traductions​

• 🇪🇪 #10339: Add Estonian theme translations.
• 🇮🇩 #10325: Add Indonesian theme translations.
• 🇪🇸 #10360: Improve Spanish theme translations.
• 🇩🇪 #10235: Improve German theme translations.
• 🇨🇳 #10257: Improve Traditional Chinese (zh-Hant) theme translations.

Autres modifications​

Voici les autres changements notables :

• #10369: Add support for pkg.pr.new continuous releases so that you can test any pull-request code in a StackBlitz playground.
• #10376: Theme unlisted/draft banners are also shown in dev so that you don't forget to publish your content.
• #10335: The Markdown top-level headings # title are automatically wrapped in <header> for consistency with front matter title: Title.
• #10286: Allows Docusaurus plugins to self-disable by returning null.
• #10241: Add support for MDX processor recmaPlugins option to modify the MDX Estree AST.
• #10324: The docs autogenerated _category_.json accepts a new description property that gets displayed on generated index pages.
• #10368: The CLI command docusaurus --version now actually returns the Docusaurus version.
• #10240: Markdown mdx-code-block now supports indentation.
• #10219: Fix <TabItem lazy> support the for className prop.
• #10313: Blog-related @docusaurus/theme-common/internal APIs have been moved to @docusaurus/plugin-content-blog/client.
• #10316: Docs-related @docusaurus/theme-common/internal APIs have been moved to @docusaurus/plugin-content-docs/client.

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

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

Points importants​

Tags files​

The docs and blog plugins both already supported a tags front matter attribute, enabling you to group related content. But tags declared inline in the front matter are not always ideal.

With #10137, you can now declare a list of pre-defined tags in a tags.yml file:

tag1:
  label: 'Tag 1'
  description: 'Tag 1 description'
  permalink: /tag-1-permalink

tag2:
  label: 'Tag 2'
  description: 'Tag 2 description'
  permalink: /tag-2-permalink

These predefined tags can be used in the front matter of your blog or docs files:

---
tags: [tag1, tag2]
---

# Title

Content

Hash Router - Experimental​

With 9859, we added a new experimental hash router config option, useful for offline browsing by opening your site locally through the file:// protocol.

export default {
  future: {
    experimental_router: 'hash',
  },
};

When this mode is turned on, Docusaurus will opt out of static site rendering, and build a client-side single page application where all routes are prefixed with /#/. A single index.html file is generated. This file can be opened locally in your browser by simply clicking it, using the browser file:// protocol. This makes it possible to distribute a Docusaurus site as a .zip file so that readers can browse it offline, without having to install anything complex on their computer apart a web browser.

Try browsing our own Docusaurus site built with the hash router:

• Docusaurus website - Hash Router web deployment
• Docusaurus website - Hash Router downloadable GitHub artifacts

Site Storage - Experimental​

Docusaurus uses the browser localStorage API to persist UI state.

But sometimes the storage space is "shared" between multiple sites using the same domain, leading to storage key conflicts. This generally happens in two cases

• when working on multiple http://localhost:3000 sites
• when hosting multiple sites under the same domain: https://example.com/site1/ and https://example.com/site2/

For this reason, we introduced a new experimental siteStorage configuration option:

export default {
  future: {
    experimental_storage: {
      type: 'localStorage',
      namespace: true,
    },
  },
};

When namespace: true is set, we apply a hash suffix to all the storage keys, making them unique to the current site (based on config.url and config.baseUrl. For example, the theme storage key becomes theme-x6f. It is also possible to provide your own custom suffix namespace: 'suffix'. We also made it possible to use type: 'sessionStorage' instead of the default localStorage.

Autres modifications​

Voici les autres changements notables :

• #10151: add Turkmen (tk) theme translations
• #10111: add Bulgarian (bg) theme translations
• #10168: fix many long overdue Markdown link resolution bugs
• #10178: the /search page now respects the contextualSearch: false setting
• #10118: fix bad pluralization on docs generated index category card description
• #10130: fix false positives reported by the broken anchor checker due to trailing slashes

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

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

Points importants​

Prepare for React 19​

The React core team recently released the first React 19 beta. They also published an upgrade guide and a React v18.3 release with new warnings to help us identify issues before upgrading to React 19.

Docusaurus v3 depends on React 18.x. When initializing a new Docusaurus sites, it will use that new React 18.3 release. It's also the case if you decide to upgrade your dependencies, or re-generate your package manager lockfile.

It turns out in its current state, Docusaurus had a few of those extra warnings to fix, notably this one immediately appearing on your dev console on any page load and navigation:

Warning: LoadableComponent uses the legacy contextTypes API which is no longer supported and will be removed in the next major release. Use React.createContext() with static contextType instead.

In #10079, we got Docusaurus ready for React 19. We fixed all the React 18.3 warnings we encountered. In case we missed any, don't hesitate to report new warnings if you see them, to us but also to other Docusaurus third-party plugin authors.

createSitemapItems​

In #10083, we introduced a new flexible createSitemapItems() hook to the sitemap plugin. This enables users to create/filter/transform/enhance the sitemap items with their own custom logic.

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        sitemap: {
          createSitemapItems: async ({
            defaultCreateSitemapItems,
            ...params
          }) => {
            const items = await defaultCreateSitemapItems(params);
            return items.filter((item) => !item.url.includes('/tags/'));
          },
        },
      },
    ],
  ],
};

Pages plugin improvements​

The Docusaurus pages plugin has historically been lagging behind the docs and blog plugins in terms of available feature.

In #10032 we normalized the options available on each core content plugins by adding a few the missing page plugins APIs related to the edit url and the last update metadata displayed at the bottom on Markdown pages.

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        pages: {
          editUrl:
            'https://github.com/facebook/docusaurus/tree/main/website/src/pages',
          editLocalizedFiles: true,
          showLastUpdateAuthor: true,
          showLastUpdateTime: true,
        },
      },
    ],
  ],
};

Autres modifications​

Voici les autres changements notables :

• #10064: new site config option siteConfig.markdown.anchors.maintainCase
• #9767: new docusaurus deploy --target-dir option
• #10042: new (experimental) plugin API: route.props
• #10060: optimizes the App entrypoint, avoid useless re-renders on navigations
• #10080: <Admonition> component can render properly without heading/icon
• #10091: <Tabs> props can now override defaults
• #10090: docusaurus serve works better with a /baseUrl/ pathname prefix
• #10070: add missing theme translations for pt-BR
• #10025: doc sidebar item label now impacts the doc pagination label

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

La mise à jour devrait être facile : comme expliqué dans notre documentation du processus de publication, les versions mineures respectent le versionnage sémantique.

Points importants​

Faster builds​

We worked hard to reduce the time it takes to build a Docusaurus site in production mode.

Between v3.1.0 and v3.2.0, several changes have been made, leading to significantly faster production builds for many sites.

Let's take an example. Our benchmark on the React Native website upgrading to v3.2 reports the following results:

• 🔥 Cold builds: 95s ➡️ 66s (~30% faster)
• 🔥 Incremental builds: 55s ➡️ 22s (~60% faster)

The results will vary depending on your site's topology and the options you turned on, but we expect the largest sites will see the most significant improvements.

Note that this is only the beginning, and Docusaurus performance can still be significantly improved, notably the bundling time and the memory consumption. Track our performance issue for upcoming improvements.

Faster Dev Server​

We also worked on improving the performance of the dev server, so that you can get a faster feedback when editing Markdown/MDX files.

The way we initially implemented content reloading wasn't great. For example, editing a blog post file would also trigger a useless reload of the unrelated docs plugin. From now on, when editing a plugin's content, only that plugin will reload. It's hard to measure precisely the impact of this change, but I estimate edits should appear in your browser at least 50% faster 🔥.

We plan to keep improving the speed of our dev server, with even more granular hot reloads, ensuring we don't run useless computations that would always keep giving the same result.

MDX partials table-of-contents​

With #9684, Docusaurus is now able to render headings coming from an imported partial into the table-of-contents.

Docusaurus and MDX allows you to import one Markdown file into another. We usually call the imported Markdown file a "partial", and use the _ prefix so that this file does not lead to the creation of a new page.

# My Doc

## Doc heading

Content is imported from another MDX file:

import ImportedDoc from './\_importedDoc.mdx';

<ImportedDoc />

## Partial heading

Some paragraph

Previously, the heading Partial heading did not appear in the table-of-contents, but now it will!

Blog improvements​

We improved the blog plugin with several new options to make it even more powerful and flexible:

• #9912: you can now display the last update time and author of a blog post, a feature the docs plugin already had.
• #9886: a new processBlogPosts option allow you to filter/transform/sort blog posts.
• #9838: a new pageBasePath option allows you to customize the blog pagination URL segment (/blog/page/2)

Sitemap lastmod​

With #9954, the sitemap plugin has a new lastmod option that can now emit a <lastmod> tag on the XML. The value is read from the Git history by default, but can be overridden with docs and blog last_update front matter.

We also made it possible to opt-out of emitting <priority> and <frequency> tags, which are generally ignored by crawlers (notably Google).

We recommend using the following sitemap plugin config, that will become the default in Docusaurus V4:

{
  lastmod: 'date',
  priority: null,
  changefreq: null,
}

Autres modifications​

• #9687: new Vercel Analytics plugin
• #9681 and #9442: docusaurus swizzle and create-docusaurus CLIs now ask users if they prefer to use TypeScript
• #9928: new Icelandic translation
• #9928: new allContentLoaded plugin lifecycle (experimental)

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

La mise à jour devrait être facile : comme expliqué dans notre documentation du processus de publication, les versions mineures respectent le versionnage sémantique.

Points importants​

Vérificateur d'ancrage défectueux​

Dans le #9528, nous avons amélioré le vérificateur intégré de liens défectueux pour qu'il détecte également les ancrages défectueux.

Hook parseFrontMatter​

Dans le #9624, nous avons ajouté une nouvelle fonction hook siteConfig.markdown.parseFrontMatter.

Cela permet de mettre en œuvre des transformations pratiques du front matter, des raccourcis, ou de s'intégrer à des systèmes externes utilisant le front matter que les plugins de Docusaurus ne prennent pas en charge.

export default {
  markdown: {
    parseFrontMatter: async (params) => {
      // Réutiliser l'analyseur par défaut
      const result = await params.defaultParseFrontMatter(params);

      // Traiter les placeholders de description de la page de garde
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');

      // Créer votre propre raccourci pour les pages de garde
      if (result.frontMatter.i_do_not_want_docs_pagination) {
        result.frontMatter.pagination_prev = null;
        result.frontMatter.pagination_next = null;
      }

      // Renommer un front matter non supporté provenant d'un autre système
      if (result.frontMatter.cms_seo_summary) {
        result.frontMatter.description = result.frontMatter.cms_seo_summary;
        delete result.frontMatter.cms_seo_summary;
      }

      return result;
    },
  },
};

Lisez le guide du front matter et la référence de l'API parseFrontMatter pour plus de détails.

Autres modifications​

Voici les autres changements notables :

• #9674 : ajout de siteConfig.markdown.remarkRehypeOptions pour passer des options à remark-rehype, ce qui permet de personnaliser des choses comme le libellé de la note de bas de page MDX
• #9671 : ajout d'un bloc de code MagicComments pour (Visual) Basic/Batch/Fortran/COBOL/ML
• #9610 : active la configuration du port CLI via la variable d'environnement PORT
• #9477 : traductions complètes en portugais brésilien (pt-BR)

Consultez l'entrée 3.1.0 du journal des modifications pour une liste exhaustive des changements.

Chez Meta Open Source, nous pensons que Docusaurus vous aidera à construire les meilleurs sites web de documentation avec un minimum d'effort, vous permettant de vous concentrer sur ce qui compte vraiment : l'écriture du contenu.

Il s'agit d'une nouvelle version majeure de Docusaurus, avec de nouvelles fonctionnalités intéressantes et des dépendances mises à jour.

Conformément aux principes du Semantic Versioning, cette version inclut des changements de rupture que nous avons documentés en détail dans le guide de mise à jour de la version 3. Les changements de rupture peuvent être gênants, mais ils sont nécessaires pour préparer le terrain à une nouvelle vague de fonctionnalités Docusaurus que nous prévoyons d'implémenter.

Nous avions initialement prévu de publier des versions majeures plus fréquemment, mais Docusaurus v3 a pris plus de temps que prévu. Parmi les changements de rupture que nous avons comptabilisés, la montée de version vers MDX v3 est probablement le principal défi à l'adoption de cette nouvelle version. Nous avons fait un effort supplémentaire pour rendre cette montée de version aussi facile que possible, notamment en ajoutant des options de compatibilité pour MDX v1.

Les sites les plus simples n'auront besoin de mettre à jour que quelques dépendances npm. Pour les sites plus complexes, nous avons élaboré quelques stratégies qui peuvent vous aider à effectuer une mise à niveau en toute confiance :

• Préparez votre site à l'avance, progressivement, tout en restant sur Docusaurus v2
• Mettez en place des tests de régression visuelle pour détecter les changements visuels inattendus survenant au cours de la mise à jour

Changements de rupture​

Cette section ne donne qu'un bref aperçu. Toutes les changements de rupture sont documentés en détail dans le guide de mise à jour de la version 3.

Docusaurus v3 a mis à jour quelques dépendances vers de nouvelles versions majeures, chacune venant avec ses propres changements de rupture :

• Node.js v16 ➡️ v18
• React v17 ➡️ v18
• MDX v1 ➡️ v3
• TypeScript v4 ➡️ v5
• prism-react-renderer v1 ➡️ v2
• react-live v2 ➡️ v4
• Mermaid v9 ➡️ v10
• import-fresh v3 ➡️ jiti v1
• remark-emoji v2 ➡️ v4

Une mise à jour typique des dépendances de package.json ressemble à ceci :

 {
   "dependencies": {
     // upgrade to Docusaurus v3
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
+    "@docusaurus/core": "3.0.0",
+    "@docusaurus/preset-classic": "3.0.0",
     // upgrade to MDX v3
-    "@mdx-js/react": "^1.6.22",
+    "@mdx-js/react": "^3.0.0",
     // upgrade to prism-react-renderer v2.0+
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "^2.1.0",
     // upgrade to React v18.0+
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
     // upgrade Docusaurus dev dependencies to v3
-    "@docusaurus/module-type-aliases": "2.4.3",
-    "@docusaurus/types": "2.4.3"
+    "@docusaurus/module-type-aliases": "3.0.0",
+    "@docusaurus/types": "3.0.0"
   }
   "engines": {
     // require Node.js 18.0+
-    "node": ">=16.14"
+    "node": ">=18.0"
   }
 }

A l'exception de MDX v3, la plupart des changements de rupture provenant de ces dépendances, qui ont été mises à jour, ont été gérés en interne pour vous : la plupart du temps, vous ne devriez pas avoir à faire quoi que ce soit. En dehors des dépendances, les seuls changements de rupture fonctionnels provenant explicitement de la base de code de Docusaurus sont les suivantes :

• #9189 : nouveau flux RSS de blog par défaut limité à 20 entrées
• #9308 : corrige et réintroduit l'admonition :::warning, supprime :::caution
• #9310 : supprime l'ancien préfixe d'identification de la barre latérale, utilisé pour les sites dont la version est antérieure à v2.0.0-beta.10 (décembre 2021)
• #7966 : refactorise les composants du thème des docs, ce qui vous oblige éventuellement à les re-swizzler

Points importants​

Voici une liste non exhaustive des nouvelles fonctionnalités utiles de cette nouvelle version. Toutes les fonctionnalités sont listées dans les notes de version de Docusaurus v3.0.0.

Markdown​

Docusaurus v3 met à jour MDX v1 en MDX v3 :

• dans #8288, nous avons mis à jour vers MDX v2 (guide de migration)
• dans #9451, nous avons mis à jour vers MDX v3 (guide de migration)

Cette nouvelle version de MDX est bien meilleure pour les rédacteurs de contenu et les auteurs de plugins, et prépare le terrain pour l'implémentation de nouvelles fonctionnalités Markdown passionnantes.

Cela nous permet notamment d'ajouter un mode CommonMark qui devrait faciliter l'adoption de Docusaurus pour les documentations existantes. Elle est actuellement facultative, expérimentale et limitée (certaines fonctionnalités de Docusaurus ne fonctionneront pas). Dans Docusaurus v3, tous les fichiers sont encore interprétés en MDX, mais nous prévoyons d'interpréter les fichiers .md en CommonMark dans une prochaine version majeure, et nous recommandons d'utiliser l'extension .mdx pour tout fichier utilisant les modules JSX ou ES.

Nous avons également introduit une nouvelle façon de configurer le Markdown globalement pour votre site, et nous prévoyons d'ajouter des options plus flexibles ultérieurement.

export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

Docusaurus utilise désormais le plugin remark-directive pour prendre en charge les admonitions. Cela vous offre également la possibilité de créer vos propres plugins Remark pour étendre Markdown avec vos propres directives personnalisées telles que :textDirective, ::leafDirective ou :::containerDirective.

ESM and TypeScript configs​

Dans #9317, nous avons ajouté la prise en charge des modules ES et des fichiers de config TypeScript, y compris la config du site, les barres latérales des docs, les plugins et les presets.

Voici 2 exemples TypeScript, vous donnant une expérience moderne avec l'autocomplétion de l'IDE :

import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'Mon Site',
  favicon: 'img/favicon.ico',
  // Votre config de site ...
  presets: [
    [
      'classic',
      {
        // Votre config de preset ...
      } satisfies Preset.Options,
    ],
  ],
  themeConfig: {
    // Votre config de thème ...
  } satisfies Preset.ThemeConfig,
};

export default config;

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  docs: ['introduction'],
};

export default sidebars;

Contenu non listé​

Docusaurus prenait déjà en charge l'option draft : true dans nos 3 plugins de contenu (docs, blog, pages), ce qui vous permet de supprimer certaines pages de vos versions de production.

Dans #8004, nous avons introduit une nouvelle option unlisted : true, qui gardera vos pages disponibles dans les constructions de production, tout en les « cachant » et en les rendant impossibles à découvrir à moins que vous n'ayez l'url. Cela permet de mettre en place des flux de travail utiles où vous pouvez facilement demander un avis sur un élément de contenu avant la publication finale.

Le contenu non listé sera :

• exclu de sitemap.xml
• exclu des résultats de référencement grâce à <meta name="robots" content="noindex, nofollow" />
• exclu des flux RSS du blog
• exclu des résultats d'Algolia DocSearch
• filtré à partir des éléments de la barre de navigation du site, des barres latérales des docs, de la barre latérale du blog, des archives du blog, des tags des pages...

Les contenus non listés affichent également une bannière afin que vous n'oubliiez pas de la désactiver une fois que votre contenu est prêt pour le grand jour. Voici un exemple d'article du blog non listé :

React 18​

Dans #8961, nous avons fait la mise à jour vers React 18. C'est important, notamment pour l'adoption progressive des fonctionnalités Concurrent de React, ainsi que pour les fonctionnalités prometteuses à venir telles que les composants de serveur React à l'exécution de la construction.

Cette nouvelle version de React devrait pouvoir remplacer la plupart des sites Docusaurus. Elle s'accompagne de changements de rupture que nous avons gérés en interne dans la base de code de Docusaurus. Si votre site utilise beaucoup de code React personnalisé, nous vous recommandons de consulter l'article officiel sur Comment passer à React 18, notamment le nouveau comportement de batching automatique.

Exécution automatique du JSX​

Docusaurus v3 utilise désormais le runtime JSX « automatique ».

Il n'est plus nécessaire d'importer React dans les fichiers JSX qui n'utilisent aucune API React.

- import React from 'react';

  export default function MyComponent() {
    return <div>Hello</div>;
  }

Débogage des constructions​

Il est maintenant possible de construire votre site statique en mode dev.

docusaurus build --dev

TypeScript​

Docusaurus v3 nécessite maintenant une version minimale de TypeScript 5.0.

Nous avons réinternalisé la config TypeScript de base recommandée dans un nouveau package officiel :

 {
-  "extends": "@tsconfig/docusaurus/tsconfig.json",
+  "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": "."
   }
 }

Nous avons également des exportations plus propres et normalisées pour le type du noyau de Docusaurus, les plugins et les options de preset, que vous pouvez utiliser dans les tous nouveaux fichiers de configuration TypeScript :

import type {Config} from '@docusaurus/types';
import type {Options, ThemeConfig} from '@docusaurus/preset-classic';
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

Blocs de code​

Dans #9316, nous avons amélioré la coloration syntaxique grâce à la mise à jour de prism-react-renderer v2. Par exemple, le paramètre bash --save est maintenant colorisé :

npm install --save some-package

L'éditeur de code interactif passe également à react-live v4, avec un nouveau compilateur sucrase. Il est plus rapide, plus léger et prend en charge des fonctionnalités modernes, notamment les annotations de type TypeScript.

function Hello() {
  const name: string = 'World';
  return <div>Hello {name}</div>;
}

Dans #8982 et #8870, nous avons également ajouté la prise en charge des commentaires magiques pour les syntaxes de commentaires de type TeX, Haskell et WebAssembly.

stringLength :: String -> Int
stringLength [] = 0
stringLength (x:xs) = 1 + stringLength xs

function result = times2(n)
  result = n * 2;
end
x = 10;
y = times2(x);

Diagrammes Mermaid​

Dans #9305, nous avons mis à jour Mermaid v10.4 et ajouté la prise en charge du rendu asynchrone des diagrammes. Docusaurus est maintenant en mesure de rendre de nouveaux types de diagrammes.

Attributs de données de la chaîne de requête​

Dans #9028, nous avons rendu possible la définition d'attributs de données HTML personnalisés à travers les paramètres de la chaîne de requête docusaurus-data-x. Cela facilite l'intégration d'un iframe Docusaurus sur un autre site et vous permet de personnaliser l'apparence de la version intégrée à l'aide de CSS.

html[data-navbar='false'] .navbar {
  display: none;
}

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}

Autres fonctionnalités​

Autres nouvelles fonctionnalités à mentionner :

• #9189 : nouvelle option du blog feedOptions.limit
• #9071 : ajout d'un support de référencement normalisé pour le plugin de pages
• #9171 : le plugin client-redirects prend désormais en charge les urls qualifiés et query-string/hash dans l'url de destination
• #9171 : nouvelle règle ESLint no-html-links
• #8384 : nouvelle règle ESLint prefer-docusaurus-heading

Consultez les notes de version de Docusaurus v3.0.0 pour une liste exhaustive des changements.

Conclusion​

Cette version est fournie avec quelques fonctionnalités, mais plus important encore, met à jour de nombreuses pièces de l'infrastructure Docusaurus.

La mise à jour MDX a consommé beaucoup de notre temps cette année, et nous avons travaillé dur pour rendre cette importante mise à jour moins difficile pour vous tous.

Maintenant que nous avons rattrapé notre retard en matière d'infrastructure, nous serons de retour pour délivrer des fonctionnalités de documentation utiles très bientôt, dans les prochaines versions mineures.

Nous vous remercions d'utiliser Docusaurus au fil des ans. Le marché des frameworks de documentation devient de plus en plus concurrentiel ces derniers temps, et nous ferons de notre mieux pour que Docusaurus reste une solution compétitive qui se distingue par sa grande flexibilité.

Docusaurus v3 est maintenant en beta et la sortie officielle est imminente. C'est le moment idéal pour commencer à préparer votre site pour cette nouvelle version majeure.

Docusaurus v3 comporte quelques changements de rupture, dont beaucoup peuvent être traités aujourd'hui avec Docusaurus v2. La préparation de votre site en amont peut se faire de manière progressive et facilitera la mise à niveau vers la v3.

Le principal changement de rupture est la mise à jour de MDX v1 vers MDX v3. Lisez les notes de version pour MDX v2 et MDX v3 pour plus de détails. MDX compile maintenant votre contenu Markdown plus strictement et avec des différences subtiles.

Cet article se concentrera principalement sur la façon de préparer votre contenu pour cette nouvelle version de MDX, et énumérera également quelques autres changements de rupture que vous pouvez traiter dès aujourd'hui.

Travaux préparatoires​

Avant de préparer la mise à niveau de Docusaurus v3, nous vous recommandons d'effectuer une mise à niveau vers la dernière version de Docusaurus v2.

En fonction de la complexité de votre site, il peut être judicieux d'adopter le flux de travail des tests de régression visuels que nous avons récemment présenté. Cela pourrait vous aider à détecter des effets secondaires visuels inattendus survenant lors de la mise à jour de Docusaurus v3.

Nous recommandons également d'utiliser l'extension .mdx chaque fois que vous utilisez JSX, import, ou export (par exemple les fonctionnalités MDX) dans un fichier Markdown. Elle est plus correcte sémantiquement et améliore la compatibilité avec les outils externes (IDE, formateurs, linters, etc.). Dans les versions futures de Docusaurus, les fichiers .md seront analysés comme du CommonMark standard, qui ne prend pas en charge ces fonctionnalités. Dans Docusaurus v3, les fichiers .md continuent d'être compilés comme des fichiers MDX, mais il sera possible d'opter pour CommonMark.

Préparation du contenu pour MDX v3​

MDX est une dépendance majeure de Docusaurus responsable de la compilation de vos fichiers .md et .mdx en composants React.

MDX v3 est bien meilleur, mais s'accompagne également de changements qui vous obligeront probablement à remanier quelque peu votre contenu. MDX v3 est plus strict, et certains composants qui se compilaient bien sous v1 peuvent maintenant ne pas se compiler sous v2, très probablement à cause des caractères { et <.

La mise à jour de MDX s'accompagne de toutes les changements de rupture documentés dans les articles du blog sur les versions MDX v2 et MDX v3. Les changements de rupture les plus importants proviennent de MDX v2. Le guide de migration MDX v2 contient une section sur la façon de mettre à jour les fichiers MDX qui sera particulièrement pertinente pour nous. Assurez-vous également de lire la page Troubleshooting MDX qui peut vous aider à interpréter les messages d'erreur MDX les plus courants.

Veillez également à lire notre page de documentation actualisée de MDX et React.

Utilisation du terrain de jeu MDX​

Le terrain de jeu du MDX est votre nouveau meilleur ami. Il permet de comprendre comment votre contenu est compilé en composants React, et de résoudre les problèmes de compilation ou de rendu de manière isolée.

Chaque version MDX est livrée avec son propre terrain de jeu :

• Terrain de jeu MDX - version actuelle
• Terrain de jeu MDX - v1

En utilisant les deux terrains de jeu MDX côte à côte, vous remarquerez rapidement que certains contenus sont compilés différemment ou ne se compilent pas dans la v3.

Utilisation du CLI de vérification du MDX​

Nous fournissons un CLI docusaurus-mdx-checker qui permet de repérer facilement les contenus problématiques. Exécutez cette commande aujourd'hui sur votre site Docusaurus v2 pour obtenir la liste des fichiers qui ne pourront pas être compilés sous MDX v3.

npx docusaurus-mdx-checker

Pour chaque problème de compilation, le CLI enregistre le chemin d'accès au fichier et un numéro de ligne à consulter.

Problèmes fréquents du MDX​

Nous avons mis à jour quelques sites Docusaurus vers Docusaurus v3 et MDX v3 :

• PR de Docusaurus
• PR de React-Native
• PR de Jest

Ces mises à jour nous ont permis de regrouper les problèmes de contenu les plus courants et de documenter la meilleure façon de les traiter.

Mauvaise utilisation de {​

Le caractère { est utilisé pour ouvrir des expressions JavaScript. Désormais, MDX échouera si ce que vous mettez dans {expression} n'est pas une expression valide.

La forme de l'objet ressemble à {username: string, age: number}

Mauvaise utilisation de <​

Le caractère < est utilisé pour ouvrir des balises JSX. Désormais, MDX échouera s'il pense que votre JSX n'est pas valide.

Utiliser la version Android <5

Vous pouvez utiliser un type générique comme Array<T>

Suivez le modèle "Road to <YOUR_MINOR_VERSION>"

Mauvaise utilisation de GFM Autolink​

Docusaurus prend en charge GitHub Flavored Markdown (GFM), mais autolink utilisant la syntaxe <link> n'est plus pris en charge par MDX.

<sebastien@thisweekinreact.com>

<http://localhost:3000>

sebastien@thisweekinreact.com
[sebastien@thisweekinreact.com](mailto:sebastien@thisweekinreact.com)

http://localhost:3000
[http://localhost:3000](http://localhost:3000)

Correspondance de MDXComponent en minuscules​

Pour les utilisateurs fournissant une correspondance MDXComponent personnalisée, les composants sont maintenant « mis en bac à sable » :

• une correspondance de MDXComponent pour h1 n'est utilisée que pour # hi mais pas pour <h1>hi</h1>
• un nom d'élément personnalisé en minuscules ne sera plus remplacé par son composant MDXComponent respectif

 import MDXComponents from '@theme-original/MDXComponents';

 export default {
   ...MDXComponents,
   p: (props) => <p {...props} className="my-paragraph"/>
-  myElement: (props) => <div {...props} className="my-class" />,
+  MyElement: (props) => <div {...props} className="my-class" />,
 };

Paragraphes supplémentaires involontaires​

Dans MDX v3, il est désormais possible d'intercaler du JSX et du Markdown plus facilement sans avoir besoin de sauts de ligne supplémentaires. L'écriture d'un contenu sur plusieurs lignes peut également produire de nouvelles balises <p> attendues.

<div>Un peu de contenu **Markdown**</div>
<div>
  Un peu de contenu **Markdown**
</div>

<div>Un peu de contenu **Markdown**</div>
<div>Un peu de contenu **Markdown**</div>

<div>Un peu de contenu <strong>Markdown</strong></div>
<div><p>Un peu de contenu <strong>Markdown</strong></p></div>

 <figure>
   <img src="/img/myImage.png" alt="My alt" />
-  <figcaption>
-    Légende de mon image
-  </figcaption>
+  <figcaption>Légende de mon image</figcaption>
 </figure>

Utilisation involontaire de directives​

Docusaurus v3 utilise désormais des directives Markdown (mises en œuvre avec remark-directive) comme moyen générique de fournir un support pour les admonitions, et d'autres fonctionnalités à venir de Docusaurus.

Ceci est un :texteDeDirective

::directiveFeuille

:::conteneurDeDirective

Contenu du conteneur de la directive

:::

La conférence AWS re:Invent est formidable

La conférence AWS re
est formidable

Blocs de code indentés non pris en charge​

MDX ne transforme plus le texte indenté comme des blocs de code.

    console.log("hello");

```js
console.log('hello');
```

Plugins MDX​

Tous les paquets officiels (Unified, Remark, Rehype...) dans l'écosystème MDX sont désormais des Modules ES uniquement et ne supportent plus [CommonJS] (https://nodejs.org/api/modules.html#modules-commonjs-modules).

En pratique, cela signifie que vous ne pouvez plus faire de require("remark-plugin").

import remarkPlugin from 'remark-plugin';

export default {
  title: 'Docusaurus',
  /* config du site à l'aide des plugins remark ici */
};

module.exports = async function () {
  const myPlugin = (await import('remark-plugin')).default;
  return {
    // config du site...
  };
};

Autres changements de rupture​

Hormis le MDX, il existe d'autres changements de rupture auxquels vous pouvez d'ores et déjà préparer votre site, notamment des montées de version majeures de dépendances importantes.

Node.js 18.0​

Node.js 16 a atteint sa fin de vie, et Docusaurus v3 nécessite désormais Node.js >= 18.0.

React 18.0​

Docusaurus v3 nécessite désormais React >= 18.0.

React 18 s'accompagne de ses propres changements de rupture qui devraient être relativement faciles à gérer, selon la quantité de code React personnalisé que vous avez créé pour votre site.

Les simples sites Docusaurus, qui n'utilisent que du code de notre thème officiel sans swizzling, n'ont aucun souci à se faire.

TypeScript 5.0​

Docusaurus v3 nécessite désormais TypeScript >= 5.0.

Configuration de base de TypeScript​

La configuration officielle de TypeScript de Docusaurus a été réinternalisée depuis le paquet externe @tsconfig/docusaurus vers notre nouveau paquet monorepo @docusaurus/tsconfig.

Ce nouveau paquet est versionné en même temps que tous les autres paquets de base de Docusaurus, et il sera utilisé pour assurer la rétro-compatibilité de TypeScript et les changements de rupture lors des mises à jour de versions majeures.

 {
   "devDependencies": {
-    "@tsconfig/docusaurus": "^1.0.7",
+    "@docusaurus/tsconfig": "^3.0.0-beta.0",
   }
 }

 {
-  "extends": "@tsconfig/docusaurus/tsconfig.json",
+  "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": "."
   }
 }

Admonition warning​

Pour des raisons historiques, nous prenons en charge un admonition non documenté :::warning qui s'affiche avec une couleur rouge.

Cependant, la couleur et l'icône sont historiquement erronées. Docusaurus v3 réintroduit officiellement l'admonition :::warning, la documente, et corrige la couleur et l'icône.

Barres latérales versionnées​

Ce changement de rupture n'affectera que les utilisateurs de Docusaurus v2 qui ont versionné leurs documents avant la v2.0.0-beta.10 (décembre 2021).

Lors de la création de la version v1.0.0, le fichier sidebar contenait un préfixe version-v1.0.0/ que Docusaurus v3 ne prend plus en charge.

{
  "version-v1.0.0/docs": [
    "version-v1.0.0/introduction",
    "version-v1.0.0/prerequisites"
  ]
}

{
  "docs": ["introduction", "prerequisites"]
}

Try Docusaurus v3 today​

Docusaurus v3 est maintenant en beta, et déjà utilisé en production par React-Native, Jest et notre propre site web.

Nous pensons que cette nouvelle version de Docusaurus est robuste et prête à être déployée en production. Il devrait être lancé officiellement bientôt, après avoir reçu un retour positif de la part des premiers utilisateurs de notre communauté.

Nous vous serions très reconnaissants d'essayer la mise à jour et de signaler les problèmes sur le fil de discussion sur la version 3.0.0-beta.0.

Pour la plupart des sites, la mise à jour devrait être facile. Si vous avez préparé votre site au préalable comme indiqué ici, la mise à jour des dépendances suivantes devrait suffire :

 {
   "dependencies": {
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
-    "@mdx-js/react": "^1.6.22",
+    "@docusaurus/core": "3.0.0-beta.0",
+    "@docusaurus/preset-classic": "3.0.0-beta.0",
+    "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^1.3.5",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.4.3"
+    "@docusaurus/module-type-aliases": "3.0.0-beta.0"
   }
 }

Demander de l’aide​

Nous serons là pour vous aider à effectuer la montée de version par le biais des canaux d'assistance suivants :

• Docusaurus v3 - Support de mise à jour
• Docusaurus v3 - Canal Discord #migration-v2-to-v3
• MDX v3 - Support de mise à jour
• MDX v3 - Support des plugins Remark/Rehype
• MDX v3 - Canal Discord #migration-mdx-v3

Vous pouvez également faire appel à un fournisseur de service Docusaurus payant pour effectuer cette montée de version à votre place. Si votre site est open source, vous pouvez également demander à notre communauté une aide gratuite et bienveillante.

Conclusion​

Docusaurus v3 est prêt à être essayé, et sera bientôt disponible. Cet article vous donne déjà une bonne idée de tous les changements majeurs nécessaires à la montée de version.

La version initiale 3.0 se concentre sur les dépendances et les mises à niveau de l'infrastructure qui nous permettront d'implémenter de nouvelles fonctionnalités intéressantes. Elle est également dotée de quelques fonctionnalités utiles que nous détaillerons dans les notes de la version finale.

La mise à jour de Docusaurus est un bon exemple : à moins de revoir toutes les pages une à une, il est difficile de s'assurer qu'il n'y a pas de régression visuelle. Docusaurus v3 est sur le point de sortir (actuellement en beta), et nous aimerions vous aider à effectuer cette mise à jour en toute confiance.

Cet article présente un flux de travail de test sur la régression visuelle basé sur GitHub Actions, Playwright et Argos. Il n'est pas directement lié à Docusaurus ou React, et peut être adapté pour fonctionner avec d'autres applications frontend et d'autres frameworks.

Ce flux de travail a été testé lors de la montée de version de Docusaurus v2 vers v3, et a déjà permis de corriger quelques régressions visuelles sur des sites tels que React Native, Jest, et le site Docusaurus lui-même.

Docusaurus v3 s'accompagne de changements d'infrastructure et de mises à niveau de dépendances majeures telles que MDX v3 et React 18, qui peuvent produire des effets secondaires inattendus. Il aurait été difficile de constater toutes les régressions visuelles en l'absence d'un tel flux de travail. C'est pourquoi nous encourageons les propriétaires de sites à adopter des tests de régression visuels, en particulier pour les sites hautement personnalisés.

Vue d'ensemble du flux de travail​

L'idée générale est assez simple :

• Construire votre site dans une CI avec GitHub Actions
• Faire des captures d'écran de toutes les pages de sitemap.xml avec Playwright
• Les télécharger sur Argos
• Faire cela pour les deux branches Git : main et pr-branch.
• Comparez les captures d'écran les unes aux autres dans Argos

Argos va alors signaler les différences visuelles trouvées entre main et pr-branch sous forme d'un statut de commit GitHub et d'un commentaire de pull-request. Cela peut vous aider à détecter les régressions visuelles en amont de manière automatisée.

Argos crée un rapport référençant toutes les différences visuelles trouvées en comparant l'un à l'autre les sites des 2 branches Git, et fournit une interface utilisateur pratique pour repérer facilement la différence.

Consultez la page Argos de Docusaurus pour explorer les rapports de notre propre site web.

Voici un exemple plus concret d'Argos signalant une régression visuelle trouvé lors de la mise à jour du site web React-Native :

Implémentation du flux de travail​

Cette section décrit les modalités de mise en place de chaque étape du flux de travail.

Vous devrez vous inscrire à Argos et connecter Argos à votre dépôt GitHub

Dépendances​

Ce flux de travail nécessite les dépendances suivantes, en plus des dépendances habituelles de Docusaurus :

yarn add -D @argos-ci/cli @argos-ci/playwright @playwright/test cheerio

GitHub Action​

GitHub action se charge de l'exécution du flux de travail pour chaque branche Git.

Un flux de travail minimal pourrait ressembler à ce qui suit :

name: Argos CI Screenshots

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  take-screenshots:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4

      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: current

      - name: Install dependencies
        run: yarn install --frozen-lockfile

      - name: Install Playwright browsers
        run: yarn playwright install --with-deps chromium

      - name: Build the website
        run: yarn docusaurus build

      - name: Take screenshots with Playwright
        run: yarn playwright test

      - name: Upload screenshots to Argos
        run: yarn argos upload ./screenshots

Config de Playwright​

Playwright se charge des captures d'écran du site web précédemment construit localement par Github action.

Une config de Playwright minimale pourrait ressembler à ce qui suit :

import {devices} from '@playwright/test';
import type {PlaywrightTestConfig} from '@playwright/test';

const config: PlaywrightTestConfig = {
  webServer: {
    port: 3000,
    command: 'yarn docusaurus serve',
  },
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
      },
    },
  ],
};

export default config;

Test de Playwright​

Une config de Playwright ne suffit pas : nous devons également écrire un fichier de test Playwright pour générer les captures d'écran du site.

import * as fs from 'fs';
import {test} from '@playwright/test';
import {argosScreenshot} from '@argos-ci/playwright';
import {extractSitemapPathnames, pathnameToArgosName} from './utils';

// Constantes
const siteUrl = 'http://localhost:3000';
const sitemapPath = './build/sitemap.xml';
const stylesheetPath = './screenshot.css';
const stylesheet = fs.readFileSync(stylesheetPath).toString();

// Attends l'hydratation, nécessite Docusaurus v2.4.3+
// Docusaurus ajoute un <html data-has-hydrated="true"> une fois l'hydratation terminée
// Consultez https://github.com/facebook/docusaurus/pull/9256
function waitForDocusaurusHydration() {
  return document.documentElement.dataset.hasHydrated === 'true';
}

function screenshotPathname(pathname: string) {
  test(`pathname ${pathname}`, async ({page}) => {
    const url = siteUrl + pathname;
    await page.goto(url);
    await page.waitForFunction(waitForDocusaurusHydration);
    await page.addStyleTag({content: stylesheet});
    await argosScreenshot(page, pathnameToArgosName(pathname));
  });
}

test.describe('Docusaurus site screenshots', () => {
  const pathnames = extractSitemapPathnames(sitemapPath);
  console.log('Pathnames to screenshot:', pathnames);
  pathnames.forEach(screenshotPathname);
});

import * as cheerio from 'cheerio';
import * as fs from 'fs';

// Extrait une liste de noms de chemin, à partir d'un chemin fs vers un fichier sitemap.xml
// Docusaurus génère un fichier build/sitemap.xml pour vous !
export function extractSitemapPathnames(sitemapPath: string): string[] {
  const sitemap = fs.readFileSync(sitemapPath).toString();
  const $ = cheerio.load(sitemap, {xmlMode: true});
  const urls: string[] = [];
  $('loc').each(function handleLoc() {
    urls.push($(this).text());
  });
  return urls.map((url) => new URL(url).pathname);
}

// Convertit un nom de chemin en un nom de capture d'écran convenable
export function pathnameToArgosName(pathname: string): string {
  return pathname.replace(/^\/|\/$/g, '') || 'index';
}