We are happy to announce Docusaurus 2.4.
The upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.
精彩内容
Sidebar item description
In #8236, we made it possible to provide a new description
attribute for docs sidebar items of type link
and category
.
[
{
type: 'link',
label: 'Link with description',
href: 'https://docusaurus.io',
description: 'Some link description',
},
{
type: 'category',
label: 'Category with description',
description: 'Some category description',
items: [],
},
];
These descriptions will be used in category generated index pages.
Theme Query String
In #8708, we added the possibility to force Docusaurus to initialize itself in light
or dark
mode through a new docusaurus-theme
query-string parameter.
This is useful to ensure a consistent theme when embedding an existing Docusaurus page into an iframe or WebView.
Remark plugin npm2yarn upgrade
In #8690, we upgraded our Remark plugin @docusaurus/remark-plugin-npm2yarn with many conversion bug fixes, first-class support for pnpm, and the ability to register custom converters producing new tabs.
Run these commands!
```bash npm2yarn
npm install
npm run build
npm run myCustomScript -- --some-arg
```
- npm
- Yarn
- pnpm
npm install
npm run build
npm run myCustomScript -- --some-arg
yarn install
yarn build
yarn myCustomScript --some-arg
pnpm install
pnpm run build
pnpm run myCustomScript -- --some-arg
gtag support for multiple tracking IDs
In #8620 we added support for the @docusaurus/plugin-google-gtag plugin to declare multiple tracking IDs.
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
gtag: {
trackingID: [
'G-<YOUR-NEW-GA4-ID>',
'UA-<YOUR-OLD-UA-ID>',
],
},
},
],
],
};
Google will sunset its Universal Analytics on July 1, 2023.
Docusaurus users should migrate to Google Analytics 4. Google does not permit to migrate your existing Universal Analytics data to your new Google Analytics 4 property.
To preserve the continuity of your analytics, we temporarily recommend that you report events to 2 tracking IDs at the same time: the old one (UA-*
) and new one (G-*
). Refer to the dedicated issue for details.
Developer Experience
In #8736, we improved how we render error messages and added initial support to render the full causal chain of an error (see ES2022 Error Cause).
To see it in action, click here:
In #8735 we also made navbar-related error messages clearer to help users understand what they did wrong.
Translations
We made it possible to translate some new elements:
- #8677 introduces a new
process.env.DOCUSAURUS_CURRENT_LOCALE
(experimental) allowing you to localize your config file, including site title, tagline, announcement bar, baseUrl... - #8616 allows to translate the navbar and footer logo alt text
We added default theme translation support for multiple languages:
Completing theme translations is an ongoing effort and an easy way to contribute to Docusaurus. We add new theme features regularly, for which we often need new translations.
其他改变:
Other notable changes include:
- #8674: respect
prefers-reduced-motion: reduce
media query - #8712: use a navbar item of type
docSidebar
in template - #8801: allow tabs children to be falsy
- #8757: make search page react to external query-string changes
- #8803: fix code block buttons position in RTL
- #8615: fix color mode toggle when using dark navbar
- #8699: fix navbar dropdown tab focus bug
Check the 2.4.0 changelog entry for an exhaustive list of changes.