mirror of
https://github.com/facebook/docusaurus.git
synced 2025-12-26 09:43:10 +00:00
3.2 blog
This commit is contained in:
sebastien
parent
c90ac8b616
commit
85a4ecd183
Binary file not shown.
|
After Width: | Height: | Size: 186 KiB |
|
|
@ -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/).
|
||||
|
||||
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
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.
|
||||
|
||||
<details>
|
||||
<summary>What is the difference between a cold build and an incremental build?</summary>
|
||||
|
||||
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.
|
||||
|
||||
</details>
|
||||
|
||||
## 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 `<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](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 `<Heading>` and `<Link>` 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.
|
||||
Loading…
Reference in New Issue