跳到主要内容
Sébastien Lorber
Docusaurus 维护者、React 周刊编者

A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.

View all authors

Docusaurus 3.6

· 阅读需 6 分钟
Sébastien Lorber
Docusaurus 维护者、React 周刊编者

We are happy to announce Docusaurus 3.6.

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.

Docusaurus blog post social card

精彩内容

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! 🔥:

How to benchmark

About rebuilds

Rspack doesn't support persistent caching yet, but it's on the roadmap and should be implemented soon. We think it's not a problem for the adoption of Rspack considering a cold Rspack build is usually as fast as a warm Webpack build using persistent caching.

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

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

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,
},
},
};
Experimental but safe

Don't be afraid to turn this feature on. What's experimental is the config options.

The new infrastructure is robust and well-tested by our CI pipeline. The Docusaurus site already uses it in production, and we plan to use it on other Meta docs sites as well.

插件

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({}),
]
};
},
};
}
For plugins authors

Check the dedicated issue for guidelines and support.

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.

Loader timeline example

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

docusaurus.config.js
export default {
plugins: [
[
'rsdoctor',
{
/* options */
},
],
],
};
提示

Turn it on conditionally, based on an environment variable:

docusaurus.config.js
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:

Translations

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

其他改变:

Other notable changes include:

  • #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.

Docusaurus 3.5

· 阅读需 4 分钟
Sébastien Lorber
Docusaurus 维护者、React 周刊编者

We are happy to announce Docusaurus 3.5.

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.

Docusaurus blog post social card

精彩内容

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.

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

Author socials screenshot displaying `slorber` author with 4 social platform icons

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:

blog/authors.yml
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.

Author page screenshot for `slorber` global author

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

Author index page listing multiple 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.

website/docusaurus.config.js
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:

website/docusaurus.config.js
const blogOptions = {
feedOptions: {
xslt: true,
},
};

Screenshot of the Docusaurus blog RSS feed, beautifully styled

Blog Sidebar Grouping

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

Screenshot of the Docusaurus blog, in particular the sidebar items grouped by year

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