diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx
index 36108adce8..c4f560eef9 100644
--- a/website/docs/guides/markdown-features/markdown-features-react.mdx
+++ b/website/docs/guides/markdown-features/markdown-features-react.mdx
@@ -9,6 +9,9 @@ slug: /markdown-features/react
```mdx-code-block
import BrowserWindow from '@site/src/components/BrowserWindow';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import styles from './markdown-features-react.module.css';
```
## Using JSX in Markdown {#using-jsx-in-markdown}
@@ -29,7 +32,7 @@ Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.ap
:::
-Try this block here:
+To define any custom component within an MDX file, you have to export it.
```jsx
export const Highlight = ({children, color}) => (
@@ -74,9 +77,25 @@ I can write **Markdown** alongside my _JSX_!
```
-
+You can also import your own components defined in other files or third-party components installed via npm.
-You can also import your own components defined in other files or third-party components installed via npm! Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
+
+```md
+
+import TOCInline from '@theme/TOCInline';
+
+import Button from '@mui/material/Button';
+
+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).
+
+:::
+
+Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
:::caution
@@ -84,6 +103,211 @@ Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore,
:::
+### 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.
+
+
+
+Samples of parsing failures
+
+**A paragraph starting with a JSX tag will be seen entirely as a JSX string:**
+
+````mdx-code-block
+
+
+
+
+```jsx
+Highlighted text but afterwards _Markdown_ **doesn't work**
+```
+
+
+
+
+
+Highlighted text but afterwards _Markdown_ **doesn't work**
+
+
+
+
+
+
+Use JSX for the rest of the line, or prefix the line with some plain text:
+
+
+
+```jsx
+Use JSX for the paragraph to stop worrying aboutMarkdown
+
+← This is a zero-width space and afterwards Markdownworks
+```
+
+
+
+
+
+Use JSX for the paragraph to stop worrying aboutMarkdown
+
+← This is a zero-width space and afterwards Markdownworks
+
+
+
+
+
+
+**Markdown within a JSX tag never works:**
+
+
+
+
+
+```jsx
+**Bold doesn't work**
+```
+
+
+
+
+
+**Bold doesn't work**
+
+
+
+
+
+
+
+Use JSX within JSX tag, or move the Markdown to the outer layer:
+
+
+
+```jsx
+Bold now works
+
+**Bold now works**
+```
+
+
+
+
+
+Bold now works
+
+**Bold now works**
+
+
+
+
+
+
+**Text immediately below a JSX tag will be seen as JSX text:**
+
+
+
+
+
+```jsx
+
+**Bold still doesn't work**
+
+```
+
+
+
+
+
+
+**Bold still doesn't work**
+
+
+
+
+
+
+
+Add an empty new line:
+
+
+
+```jsx
+
+
+**Bold now works**
+
+
+```
+
+
+
+
+
+
+**Bold now works**
+
+
+
+
+
+
+
+**Markdown text indented by four spaces will be seen as a code block:**
+
+
+
+
+
+```jsx
+
+
+ You may think I'm just some text...
+
+
+```
+
+
+
+
+
+
+
+ You may think I'm just some text...
+
+
+
+
+
+
+
+
+Don't indent:
+
+
+
+```jsx
+
+
+Now I'm actually just text
+
+
+```
+
+
+
+
+
+
+Now I'm actually just text
+
+
+
+
+
+
+````
+
+
+
## Importing code snippets {#importing-code-snippets}
You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to [Webpack raw-loader](https://webpack.js.org/loaders/raw-loader/). In order to use `raw-loader`, you first need to install it in your project:
diff --git a/website/docs/guides/markdown-features/markdown-features-react.module.css b/website/docs/guides/markdown-features/markdown-features-react.module.css
new file mode 100644
index 0000000000..8d9f5bcbf5
--- /dev/null
+++ b/website/docs/guides/markdown-features/markdown-features-react.module.css
@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+
+.wrappingBlock {
+ width: 50%;
+ display: inline-block;
+ padding: 5px;
+ vertical-align: top;
+}
+
+.wrappingBlock code[class^=codeBlockLines] {
+ white-space: pre-wrap;
+}