From c7da6f5dd36ca95202e9f7ac45b7a43fa61c68fc Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Mon, 10 Jan 2022 20:05:33 +0800 Subject: [PATCH] docs: document MD and JSX interoperability issues (#6307) --- .../markdown-features-react.mdx | 230 +++++++++++++++++- .../markdown-features-react.module.css | 17 ++ 2 files changed, 244 insertions(+), 3 deletions(-) create mode 100644 website/docs/guides/markdown-features/markdown-features-react.module.css 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 about Markdown + +​← This is a zero-width space and afterwards Markdown works +``` + +
+
+ + +Use JSX for the paragraph to stop worrying about Markdown + +​← This is a zero-width space and afterwards Markdown works + + +
+ + + +**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; +}