docs: multiple doc improvements (#6449)

website/docs/browser-support.md

@@ -7,7 +7,28 @@ Docusaurus allows sites to define the list of supported browsers through a [brow
 
 ## Purpose {#purpose}
 
-Websites need to balance between backward compatibility and bundle size. As old browsers do not support modern APIs or syntax, more code is needed to implement the same functionality, penalizing all other users with increased site load time. As a tradeoff, the Docusaurus bundler only supports browser versions defined in the browser list.
+Websites need to balance between backward compatibility and bundle size. As old browsers do not support modern APIs or syntax, more code is needed to implement the same functionality.
+
+For example, you may use the [optional chaining syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining):
+
+```js
+const value = obj?.prop?.val;
+```
+
+...which unfortunately is only recognized by browser versions released after 2020. To be compatible with earlier browser versions, when building your site for production, our JS loader will transpile your code to a more verbose syntax:
+
+```js
+var _obj, _obj$prop;
+
+const value =
+  (_obj = obj) === null || _obj === void 0
+    ? void 0
+    : (_obj$prop = _obj.prop) === null || _obj$prop === void 0
+    ? void 0
+    : _obj$prop.val;
+```
+
+However, this penalizes all other users with increased site load time because the 29-character line now becomes 168 characters—a 6-fold increase! (In practice, it will be better because the names used will be shorter.) As a tradeoff, the JS loader only transpiles the syntax to the degree that's supported by all browser versions defined in the browser list.
 
 The browser list by default is provided through the `package.json` file as a root `browserslist` field.
 
@@ -55,29 +76,28 @@ You can "evaluate" any config with the `browserlist` cli to obtain the actual li
 npx browserslist --env="production"
 ```
 
-The output is all browsers supported in production. Below is the output in December 2021:
+The output is all browsers supported in production. Below is the output in January 2022:
 
 ```text
-and_chr 95
+and_chr 96
 and_uc 12.12
+chrome 96
 chrome 95
 chrome 94
-chrome 93
+edge 96
-chrome 92
+firefox 95
-edge 95
+firefox 94
-edge 94
-firefox 93
-firefox 92
 ie 11
-ios_saf 15
+ios_saf 15.2
+ios_saf 15.0-15.1
 ios_saf 14.5-14.8
 ios_saf 14.0-14.4
 ios_saf 12.2-12.5
-opera 79
+opera 82
-safari 15
+opera 81
+safari 15.1
 safari 14.1
 safari 13.1
-samsung 15.0
 ```
 
 ## Read more {#read-more}

website/docs/guides/markdown-features/markdown-features-intro.mdx

@@ -12,8 +12,6 @@ Documentation is one of your product's interfaces with your users. A well-writte
 
 Docusaurus 2 uses modern tooling to help you compose your interactive documentation with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
 
-In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example.
-
 :::important
 
 This section assumes you are using the official Docusaurus content plugins.

website/docs/guides/markdown-features/markdown-features-math-equations.mdx

@@ -18,14 +18,14 @@ Please read [KaTeX](https://katex.org) documentation for more details.
 Write inline math equations by wrapping LaTeX equations between `$`:
 
 ```mdx
-Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)=
+Let $f\colon[a,b] \to \R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be $F(x)=
-\int_{a}^{x}f(t)dt$. Then $$F$$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.
+\int_{a}^{x} f(t)\,dt$. Then $$F$$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.
 ```
 
 <BrowserWindow>
 
-Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)=
+Let $f\colon[a,b] \to \R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be $F(x)=
-\int_{a}^{x}f(t)dt$. Then $F$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.
+\int_{a}^{x} f(t)\,dt$. Then $F$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.
 
 </BrowserWindow>
 
@@ -35,14 +35,14 @@ For equation block or display mode, use line breaks and `$$`:
 
 ```mdx
 $$
-I = \int_0^{2\pi} \sin(x) dx
+I = \int_0^{2\pi} \sin(x)\,dx
 $$
 ```
 
 <BrowserWindow>
 
 $$
-I = \int_0^{2\pi} \sin(x) dx
+I = \int_0^{2\pi} \sin(x)\,dx
 $$
 
 </BrowserWindow>

website/docs/guides/markdown-features/markdown-features-react.mdx

@@ -24,14 +24,6 @@ While Docusaurus parses both `.md` and `.mdx` files using MDX, some of the synta
 
 :::
 
-:::caution
-
-MDX is not [100% compatible with CommonMark](https://github.com/facebook/docusaurus/issues/3018).
-
-Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX.
-
-:::
-
 To define any custom component within an MDX file, you have to export it.
 
 ```jsx
@@ -77,6 +69,26 @@ I can write **Markdown** alongside my _JSX_!
 </BrowserWindow>
 ```
 
+:::caution MDX is JSX
+
+Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects.
+
+<!-- prettier-ignore -->
+```jsx
+/* Instead of this: */
+<span style="background-color: red">Foo</span>
+/* Use this: */
+<span style={{backgroundColor: 'red'}}>Foo</span>
+```
+
+This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.md#convert-style-attributes-to-style-objects-in-mdx).
+
+In addition, MDX is not [100% compatible with CommonMark](https://github.com/facebook/docusaurus/issues/3018). Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX.
+
+:::
+
+### Importing components
+
 You can also import your own components defined in other files or third-party components installed via npm.
 
 <!-- prettier-ignore -->
@@ -91,18 +103,36 @@ import BrowserWindow from '@site/src/components/BrowserWindow';
 
 :::tip
 
-The `@site` alias points to your website's directory, where the `docusaurus.config.js` file is. Using an alias instead of relative paths (`'../../src/components/BrowserWindow'`) saves you from updating import paths when moving files around, or when [versioning docs](../docs/versioning.md) and [translating](../../i18n/i18n-tutorial.md).
+The `@site` alias points to your website's directory, usually where the `docusaurus.config.js` file is. Using an alias instead of relative paths (`'../../src/components/BrowserWindow'`) saves you from updating import paths when moving files around, or when [versioning docs](../docs/versioning.md) and [translating](../../i18n/i18n-tutorial.md).
 
 :::
 
+While declaring components within Markdown is very convenient for simple cases, it becomes hard to maintain because of limited editor support, risks of parsing errors, and low reusability. Use a separate `.js` file when your component involves complex JS logic:
+
+```jsx title="src/components/Highlight.js"
+export default function Highlight({children, color}) {
+  return (
+    <span
+      style={{
+        backgroundColor: color,
+        borderRadius: '2px',
+        color: '#fff',
+        padding: '0.2rem',
+      }}>
+      {children}
+    </span>
+  );
+}
+```
+
+```md title="markdown-file.mdx"
+import Highlight from '@site/src/components/Highlight';
+
+<Highlight color="#25c2a0">Docusaurus green</Highlight>
+```
+
 Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
 
-:::caution
-
-Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.md#convert-style-attributes-to-style-objects-in-mdx).
-
-:::
-
 ### Markdown and JSX interoperability
 
 Docusaurus v2 is using MDX v1, which has a lot of known cases where the content fails to be correctly parsed as Markdown. Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX.