diff --git a/website/blog/releases/3.2/img/social-card.png b/website/blog/releases/3.2/img/social-card.png new file mode 100644 index 0000000000..5d4d489716 Binary files /dev/null and b/website/blog/releases/3.2/img/social-card.png differ diff --git a/website/blog/releases/3.2/index.mdx b/website/blog/releases/3.2/index.mdx new file mode 100644 index 0000000000..feb3635918 --- /dev/null +++ b/website/blog/releases/3.2/index.mdx @@ -0,0 +1,181 @@ +--- +title: Docusaurus 3.2 +authors: [slorber] +tags: [release] +image: ./img/social-card.png +date: 2024-03-29 +--- + +We are happy to announce **Docusaurus 3.2**. + +The upgrade should be easy: as explained in our [release process documentation](/community/release-process), minor versions respect [Semantic Versioning](https://semver.org/). + +![Docusaurus blog post social card](./img/social-card.png) + + + +import BrowserWindow from '@site/src/components/BrowserWindow'; +import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow'; +import ErrorBoundaryTestButton from '@site/src/components/ErrorBoundaryTestButton'; + +## Highlights + +### 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](https://github.com/facebook/react-native-website/pull/4072) 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](https://github.com/facebook/docusaurus/issues/4765) for upcoming improvements. + +
+ What is the difference between a cold build and an incremental build? + +A cold build is when the Docusaurus caches are empty, generally after running `docusaurus clear`. + +An incremental build happens when you run another time the `docusaurus build` command. Docusaurus automatically tries to "re-use" computations from former builds to make subsequent builds faster. In practice it's based on [Webpack persistent caching](https://webpack.js.org/guides/build-performance/#persistent-cache). To enable incremental builds on your CI server, you can persist the `node_modules/.cache` folder across builds. + +
+ +## 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. + +## Blog improvements + +We improved the blog plugin with several new options to make it even more powerful and flexible: + +- [#9912](https://github.com/facebook/docusaurus/pull/9912): you can now display the last update time and author of a blog post, a feature the docs plugin already had. +- [#9886](https://github.com/facebook/docusaurus/pull/9886): a new `processBlogPosts` option allow you to filter/transform/sort blog posts. +- [#9838](https://github.com/facebook/docusaurus/pull/9838): a new `pageBasePath` option allows you to customize the blog pagination URL segment (`/blog/page/2`) + +## Sitemap improvements + +With [#9954](https://github.com/facebook/docusaurus/pull/9954), the sitemap plugin has a new `lastmod` option that can now emit a `` 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 `` and `` tags, which are generally ignored by crawlers (notably [Google](https://developers.google.com/search/blog/2023/06/sitemaps-lastmod-ping)). + +We recommend to use the following sitemap plugin config, that will become the default in Docusaurus V4: + +```js +{ + lastmod: 'date', + priority: null, + changefreq: null, +} +``` + +--- + +PERF: + +- cold builds +- incremental builds + +- sitemap lastmod: https://github.com/facebook/docusaurus/pull/9954 +- blog last update date/time: https://github.com/facebook/docusaurus/pull/9912 +- blog processBlogPosts: https://github.com/facebook/docusaurus/pull/9886 +- blog pageBasePath: https://github.com/facebook/docusaurus/pull/9838 + +Other: + +- Vercel Analytics plugin: https://github.com/facebook/docusaurus/pull/9687 +- Icelandic translation: https://github.com/facebook/docusaurus/pull/9928 +- allContentLoaded plugin lifecycle: https://github.com/facebook/docusaurus/pull/9931 + +- CLI prompt user for TS? https://github.com/facebook/docusaurus/pull/9681 + https://github.com/facebook/docusaurus/pull/9442 + +--- + +--- + +--- + +--- + +--- + +--- + +--- + +### Broken anchors checker + +In [#9528](https://github.com/facebook/docusaurus/pull/9528), we improved the built-in broken links checker to also detect broken anchors. + +:::tip[Make it fail fast] + +The new [`onBrokenAnchors`](/docs/api/docusaurus-config#onBrokenAnchors) option has value `warn` by default, for retro-compatibility reasons. + +We recommend to turn it to `throw` and fail your CI builds instead of deploying broken anchors to productions. + +::: + +:::note + +For users and plugin authors implementing custom `` and `` components, we provide a new [`useBrokenLinks`](/docs/docusaurus-core#useBrokenLinks) React hook API. + +**Most Docusaurus users don't need to care about it**, built-in components (`docusaurus/Link` and `@theme/Heading`) already use it internally. + +::: + +### `parseFrontMatter` hook + +In [#9624](https://github.com/facebook/docusaurus/pull/9624), we added a new [`siteConfig.markdown.parseFrontMatter` function hook](/docs/api/docusaurus-config#markdown). + +This makes it possible to implement convenient front matter transformations, shortcuts, or to integrate with external systems using front matter that Docusaurus plugins do not support. + +```js title="docusaurus.config.js" +export default { + markdown: { + // highlight-start + parseFrontMatter: async (params) => { + // Reuse the default parser + const result = await params.defaultParseFrontMatter(params); + + // Process front matter description placeholders + result.frontMatter.description = + result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE'); + + // Create your own front matter shortcut + if (result.frontMatter.i_do_not_want_docs_pagination) { + result.frontMatter.pagination_prev = null; + result.frontMatter.pagination_next = null; + } + + // Rename an unsupported front matter coming from another system + if (result.frontMatter.cms_seo_summary) { + result.frontMatter.description = result.frontMatter.cms_seo_summary; + delete result.frontMatter.cms_seo_summary; + } + + return result; + }, + // highlight-end + }, +}; +``` + +Read the [front matter guide](/docs/markdown-features#front-matter) and the [`parseFrontMatter` API ref](/docs/api/docusaurus-config#markdown) for details. + +## Other changes + +Other notable changes include: + +- [#9674](https://github.com/facebook/docusaurus/pull/9674): add `siteConfig.markdown.remarkRehypeOptions` to pass options to `remark-rehype`, letting you customize things such as MDX footnote label +- [#9671](https://github.com/facebook/docusaurus/pull/9671): add code block MagicComments support for (Visual) Basic/Batch/Fortran/COBOL/ML +- [#9610](https://github.com/facebook/docusaurus/pull/9610): enable CLI port configuration via `PORT` environment variable +- [#9477](https://github.com/facebook/docusaurus/pull/9477): complete Brazilian Portuguese (pt-BR) translations + +Check the **[3.1.0 changelog entry](/changelog/3.1.0)** for an exhaustive list of changes.