diff --git a/website/docs/browser-support.md b/website/docs/browser-support.md index 0161d041f4..86dcae792a 100644 --- a/website/docs/browser-support.md +++ b/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 -chrome 92 -edge 95 -edge 94 -firefox 93 -firefox 92 +edge 96 +firefox 95 +firefox 94 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 -safari 15 +opera 82 +opera 81 +safari 15.1 safari 14.1 safari 13.1 -samsung 15.0 ``` ## Read more {#read-more} diff --git a/website/docs/guides/markdown-features/markdown-features-intro.mdx b/website/docs/guides/markdown-features/markdown-features-intro.mdx index 11de81bc13..0f5c99cca3 100644 --- a/website/docs/guides/markdown-features/markdown-features-intro.mdx +++ b/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. diff --git a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx b/website/docs/guides/markdown-features/markdown-features-math-equations.mdx index fb681efbdc..f329431be2 100644 --- a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx +++ b/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)= -\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)$. +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)$. ``` -Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[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)$. +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)$. @@ -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 $$ ``` $$ -I = \int_0^{2\pi} \sin(x) dx +I = \int_0^{2\pi} \sin(x)\,dx $$ diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 129ec96be7..b58fe8172c 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/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_! ``` +:::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. + + +```jsx +/* Instead of this: */ +Foo +/* Use this: */ +Foo +``` + +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. @@ -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 ( + + {children} + + ); +} +``` + +```md title="markdown-file.mdx" +import Highlight from '@site/src/components/Highlight'; + +Docusaurus green +``` + 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.