facebook · slorber · Mar 23, 2023 · Mar 23, 2023 · Mar 23, 2023 · Mar 23, 2023
@@ -1,5 +1,69 @@
 # Docusaurus 2 Changelog
 
+## 2.4.0 (2023-03-23)
+
+#### :rocket: New Feature
+
+- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`
+  - [#8236](https://github.com/facebook/docusaurus/pull/8236) feat(content-docs): add support for sidebar item category/link descriptions in generated index page ([@ZarakiKanzaki](https://github.com/ZarakiKanzaki))
+- `docusaurus-theme-classic`
+  - [#8708](https://github.com/facebook/docusaurus/pull/8708) feat(theme): allow to load a Docusaurus page with theme from query-string: ?docusaurus-theme=dark ([@slorber](https://github.com/slorber))
+  - [#8616](https://github.com/facebook/docusaurus/pull/8616) feat(theme): add ability to translate navbar+footer logo alt text ([@Mysterious-Dev](https://github.com/Mysterious-Dev))
+- `docusaurus-remark-plugin-npm2yarn`
+  - [#8690](https://github.com/facebook/docusaurus/pull/8690) feat(npm-to-yarn): add support for PnPm and custom converters ([@armano2](https://github.com/armano2))
+- `docusaurus`
+  - [#8677](https://github.com/facebook/docusaurus/pull/8677) feat(core): add script env variables: NODE_ENV + BABEL_ENV + DOCUSAURUS_CURRENT_LOCALE (temporary i18n workaround) ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#8674](https://github.com/facebook/docusaurus/pull/8674) feat(theme-classic): respect `prefers-reduced-motion: reduce` mediaquery, bump Infima to alpha.43 ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-translations`
+  - [#8668](https://github.com/facebook/docusaurus/pull/8668) feat(theme-translations): add Hungarian theme translations ([@trueqap](https://github.com/trueqap))
+  - [#8631](https://github.com/facebook/docusaurus/pull/8631) feat(theme-translations): add Norwegian (Bokmål) theme translation ([@dr0nn1](https://github.com/dr0nn1))
+- `docusaurus-theme-common`
+  - [#8656](https://github.com/facebook/docusaurus/pull/8656) feat(theme-common): allow passing a string for details summary ([@pReya](https://github.com/pReya))
+- `docusaurus-plugin-google-gtag`
+  - [#8620](https://github.com/facebook/docusaurus/pull/8620) feat(gtag-plugin): gtag should support multiple tracking ids, notably for the UA => GA4 transition ([@slorber](https://github.com/slorber))
+
+#### :bug: Bug Fix
+
+- `docusaurus-theme-classic`
+  - [#8803](https://github.com/facebook/docusaurus/pull/8803) fix(theme): codeblock buttons should be kept on the right when using RTL locale ([@Vishruta-Patil](https://github.com/Vishruta-Patil))
+  - [#8615](https://github.com/facebook/docusaurus/pull/8615) fix(theme): improve color toggle when using dark navbar ([@dewanshDT](https://github.com/dewanshDT))
+  - [#8699](https://github.com/facebook/docusaurus/pull/8699) fix(theme-classic): fix tab focus bug in dropdown (#8697) ([@kagankan](https://github.com/kagankan))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#8801](https://github.com/facebook/docusaurus/pull/8801) fix(theme): allow tabs children to be falsy ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-theme-common`, `docusaurus-theme-search-algolia`
+  - [#8757](https://github.com/facebook/docusaurus/pull/8757) fix(search): search page should react to querystring changes + cleanup/refactor ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#8746](https://github.com/facebook/docusaurus/pull/8746) fix(core): baseUrl error banner link anchor case ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-translations`
+  - [#8744](https://github.com/facebook/docusaurus/pull/8744) fix(theme-translations): fix wrong arabic words (tip/next) ([@Anasqx](https://github.com/Anasqx))
+
+#### :nail_care: Polish
+
+- `create-docusaurus`
+  - [#8712](https://github.com/facebook/docusaurus/pull/8712) polish(create-docusaurus): the starter template should use a navbar item "docSidebar" instead of "doc" (less fragile on updates) ([@biplavmz](https://github.com/biplavmz))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-utils-common`, `docusaurus`
+  - [#8735](https://github.com/facebook/docusaurus/pull/8735) polish(theme): better error messages on navbar item rendering failures + ErrorCauseBoundary API ([@tannerdolby](https://github.com/tannerdolby))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus`
+  - [#8736](https://github.com/facebook/docusaurus/pull/8736) polish(core): better styling for error screens ([@tannerdolby](https://github.com/tannerdolby))
+
+#### Committers: 14
+
+- Anas ([@Anasqx](https://github.com/Anasqx))
+- Armano ([@armano2](https://github.com/armano2))
+- Davide Donadio ([@ZarakiKanzaki](https://github.com/ZarakiKanzaki))
+- Dewansh Thakur ([@dewanshDT](https://github.com/dewanshDT))
+- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena))
+- Kagan ([@kagankan](https://github.com/kagankan))
+- Moritz Stückler ([@pReya](https://github.com/pReya))
+- Mysterious_Dev ([@Mysterious-Dev](https://github.com/Mysterious-Dev))
+- Petter Drønnen ([@dr0nn1](https://github.com/dr0nn1))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Tanner Dolby ([@tannerdolby](https://github.com/tannerdolby))
+- TrueQAP ([@trueqap](https://github.com/trueqap))
+- Vishruta Patil ([@Vishruta-Patil](https://github.com/Vishruta-Patil))
+- [@biplavmz](https://github.com/biplavmz)
+
 ## 2.3.1 (2023-02-03)
 
 #### :bug: Bug Fix

@@ -25,6 +25,7 @@ beforeinstallprompt
 bhatt
 blocklist
 blockquotes
+Bokmål
 browserslist
 browserstack
 buble

@@ -8,20 +8,7 @@
 import React from 'react';
 import Layout from '@theme/Layout';
 import Heading from '@theme/Heading';
-import BrowserWindow from '@site/src/components/BrowserWindow';
-
-function IframeTest({url}: {url: string}) {
-  return (
-    <div style={{padding: 10}}>
-      <BrowserWindow
-        url={url}
-        style={{minWidth: '40vw', maxWidth: 400}}
-        bodyStyle={{padding: 0}}>
-        <iframe src={url} title={url} style={{width: '100%', height: 300}} />
-      </BrowserWindow>
-    </div>
-  );
-}
+import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow';
 
 // See https://github.com/facebook/docusaurus/issues/8672
 export default function Embeds(): JSX.Element {
@@ -30,12 +17,12 @@ export default function Embeds(): JSX.Element {
       <div style={{padding: 10}}>
         <Heading as="h1">Test Embeds</Heading>
         <div style={{display: 'flex', flexWrap: 'wrap'}}>
-          <IframeTest url="/?docusaurus-theme=light" />
-          <IframeTest url="/?docusaurus-theme=dark" />
-          <IframeTest url="/?docusaurus-theme=unexpected-value" />
-          <IframeTest url="/" />
-          <IframeTest url="https://docusaurus.io/" />
-          <IframeTest url="https://tutorial.docusaurus.io/" />
+          <IframeWindow url="/?docusaurus-theme=light" />
+          <IframeWindow url="/?docusaurus-theme=dark" />
+          <IframeWindow url="/?docusaurus-theme=unexpected-value" />
+          <IframeWindow url="/" />
+          <IframeWindow url="https://docusaurus.io/" />
+          <IframeWindow url="https://tutorial.docusaurus.io/" />
         </div>
       </div>
     </Layout>

@@ -0,0 +1,161 @@
+---
+title: Docusaurus 2.4
+authors: [slorber]
+tags: [release]
+image: ./img/social-card.png
+date: 2023-03-23
+---
+
+We are happy to announce **Docusaurus 2.4**.
+
+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)
+
+<!--truncate-->
+
+import BrowserWindow from '@site/src/components/BrowserWindow';
+import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow';
+import ErrorBoundaryTestButton from '@site/src/components/ErrorBoundaryTestButton';
+
+## Highlights
+
+### Sidebar item description
+
+In [#8236](https://github.com/facebook/docusaurus/pull/8236), we made it possible to provide a new `description` attribute for docs sidebar items of type `link` and `category`.
+
+```tsx title="sidebars.js"
+[
+  {
+    type: 'link',
+    label: 'Link with description',
+    href: 'https://docusaurus.io',
+    // highlight-next-line
+    description: 'Some link description',
+  },
+  {
+    type: 'category',
+    label: 'Category with description',
+    // highlight-next-line
+    description: 'Some category description',
+    items: [],
+  },
+];
+```
+
+These descriptions will be used in category generated index pages.
+
+![Show sidebar category generated index with custom descriptions](./img/sidebar-item-description.jpg)
+
+### Theme Query String
+
+In [#8708](https://github.com/facebook/docusaurus/pull/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.
+
+<IframeWindow url="/docs/?docusaurus-theme=light" />
+<IframeWindow url="/docs/?docusaurus-theme=dark" />
+
+### Remark plugin npm2yarn upgrade
+
+In [#8690](https://github.com/facebook/docusaurus/pull/8690), we upgraded our Remark plugin [@docusaurus/remark-plugin-npm2yarn](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-remark-plugin-npm2yarn) with many conversion bug fixes, first-class support for pnpm, and the ability to register custom converters producing new tabs.
+
+````markdown
+Run these commands!
+
+```bash npm2yarn
+npm install
+npm run build
+npm run myCustomScript -- --some-arg
+```
+````
+
+<BrowserWindow>
+
+```bash npm2yarn
+npm install
+npm run build
+npm run myCustomScript -- --some-arg
+```
+
+</BrowserWindow>
+
+### gtag support for multiple tracking IDs
+
+In [#8620](https://github.com/facebook/docusaurus/pull/8620) we added support for the [@docusaurus/plugin-google-gtag](/docs/api/plugins/@docusaurus/plugin-google-gtag) plugin to declare multiple tracking IDs.
+
+```js title="docusaurus.config.js"
+module.exports = {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        gtag: {
+          trackingID: [
+            // highlight-next-line
+            'G-<YOUR-NEW-GA4-ID>',
+            // highlight-next-line
+            'UA-<YOUR-OLD-UA-ID>',
+          ],
+        },
+      },
+    ],
+  ],
+};
+```
+
+:::caution Google is sunsetting Universal Analytics
+
+**[Google will sunset its Universal Analytics](https://blog.google/products/marketingplatform/analytics/prepare-for-future-with-google-analytics-4/)** 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](https://github.com/facebook/docusaurus/issues/7221)** for details.
+
+:::
+
+### Developer Experience
+
+In [#8736](https://github.com/facebook/docusaurus/pull/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](https://h3manth.com/ES2022/#error-cause)).
+
+:::tip
+
+To see it in action, click here: <ErrorBoundaryTestButton cause="Probably undefined is not a function 😄"/>
+
+:::
+
+In [#8735](https://github.com/facebook/docusaurus/pull/8735) we also made navbar-related error messages clearer to help users understand what they did wrong.
+
+![Docusaurus navbar error message screenshot](./img/navbar-error.jpg)
+
+### Translations
+
+We made it possible to translate some new elements:
+
+- [#8677](https://github.com/facebook/docusaurus/pull/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](https://github.com/facebook/docusaurus/pull/8616) allows to translate the navbar and footer logo alt text
+
+We added default theme translation support for multiple languages:
+
+- 🇭🇺 [#8668](https://github.com/facebook/docusaurus/pull/8668): Hungarian
+- 🇳🇴 [#8631](https://github.com/facebook/docusaurus/pull/8631): Norwegian (Bokmål)
+
+:::tip
+
+Completing theme translations is an [ongoing effort](https://github.com/facebook/docusaurus/issues/3526) and an easy way to contribute to Docusaurus. We add new theme features regularly, for which we often [need new translations](https://github.com/facebook/docusaurus/issues/3526).
+
+:::
+
+## Other changes
+
+Other notable changes include:
+
+- [#8674](https://github.com/facebook/docusaurus/pull/8674): respect `prefers-reduced-motion: reduce` media query
+- [#8712](https://github.com/facebook/docusaurus/pull/8712): use a navbar item of type `docSidebar` in template
+- [#8801](https://github.com/facebook/docusaurus/pull/8801): allow tabs children to be falsy
+- [#8757](https://github.com/facebook/docusaurus/pull/8757): make search page react to external query-string changes
+- [#8803](https://github.com/facebook/docusaurus/pull/8803): fix code block buttons position in RTL
+- [#8615](https://github.com/facebook/docusaurus/pull/8615): fix color mode toggle when using dark navbar
+- [#8699](https://github.com/facebook/docusaurus/pull/8699): fix navbar dropdown tab focus bug
+
+Check the **[2.4.0 changelog entry](/changelog/2.4.0)** for an exhaustive list of changes.
@@ -357,6 +357,7 @@ const config = {
             }
             return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`;
           },
+          remarkPlugins: [npm2yarn],
           postsPerPage: 5,
           feedOptions: {
             type: 'all',

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+
+import BrowserWindow from './index';
+
+// Quick and dirty component, to improve later if needed
+export default function IframeWindow({url}: {url: string}): JSX.Element {
+  return (
+    <div style={{padding: 10}}>
+      <BrowserWindow
+        url={url}
+        style={{
+          minWidth: 'min(100%,45vw)',
+          width: 800,
+          maxWidth: '100%',
+          overflow: 'hidden',
+        }}
+        bodyStyle={{padding: 0}}>
+        <iframe
+          src={url}
+          title={url}
+          style={{display: 'block', width: '100%', height: 300}}
+        />
+      </BrowserWindow>
+    </div>
+  );
+}
@@ -51,3 +51,17 @@ export default function BrowserWindow({
     </div>
   );
 }
+
+// Quick and dirty component, to improve later if needed
+export function IframeWindow({url}: {url: string}): JSX.Element {
+  return (
+    <div style={{padding: 10}}>
+      <BrowserWindow
+        url={url}
+        style={{minWidth: '40vw', maxWidth: 400}}
+        bodyStyle={{padding: 0}}>
+        <iframe src={url} title={url} style={{width: '100%', height: 300}} />
+      </BrowserWindow>
+    </div>
+  );
+}
@@ -9,15 +9,24 @@ import React, {type ReactNode, useState} from 'react';
 
 export default function ErrorBoundaryTestButton({
   children = 'Boom!',
+  message = 'Boom!\nSomething bad happened, but you can try again!',
+  cause,
 }: {
   children?: ReactNode;
+  message?: string;
+  cause?: string;
 }): JSX.Element {
   const [state, setState] = useState(false);
   if (state) {
-    throw new Error('Boom!\nSomething bad happened, but you can try again!');
+    throw new Error(message, {
+      cause: cause ? new Error(cause) : undefined,
+    });
   }
   return (
-    <button type="button" onClick={() => setState(true)}>
+    <button
+      className="button button--danger"
+      type="button"
+      onClick={() => setState(true)}>
       {children}
     </button>
   );

@@ -0,0 +1,28 @@
+---
+description: How Docusaurus works to build your app
+---
+
+# Architecture
+
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Zoom from 'react-medium-image-zoom';
+```
+
+<Zoom>
+
+![Architecture overview](/img/architecture.png)
+
+</Zoom>
+
+This diagram shows how Docusaurus works to build your app. Plugins each collect their content and emit JSON data; themes provide layout components which receive the JSON data as route modules. The bundler bundles all the components and emits a server bundle and a client bundle.
+
+Although you (either plugin authors or site creators) are writing JavaScript all the time, bear in mind that the JS is actually run in different environments:
+
+- All plugin lifecycle methods are run in Node. Therefore, until we support ES Modules in our codebase, plugin source code must be provided as CommonJS that can be `require`'d.
+- The theme code is built with Webpack. They can be provided as ESM—following React conventions.
+
+Plugin code and theme code never directly import each other: they only communicate through protocols (in our case, through JSON temp files and calls to `addRoute`). A useful mental model is to imagine that the plugins are not written in JavaScript, but in another language like Rust. The only way to interact with plugins for the user is through `docusaurus.config.js`, which itself is run in Node (hence you can use `require` and pass callbacks as plugin options).
+
+During bundling, the config file itself is serialized and bundled, allowing the theme to access config options like `themeConfig` or `baseUrl` through [`useDocusaurusContext()`](../docusaurus-core.mdx#useDocusaurusContext). However, the `siteConfig` object only contains **serializable values** (values that are preserved after `JSON.stringify()`). Functions, regexes, etc. would be lost on the client side. The `themeConfig` is designed to be entirely serializable.