From 57356b0812610d5e4c27c3beeac5f6a444618954 Mon Sep 17 00:00:00 2001 From: sebastienlorber Date: Thu, 27 Apr 2023 19:02:04 +0200 Subject: [PATCH 1/4] Rewrite some docs for mdx v2 --- project-words.txt | 2 + .../markdown-features-plugins.mdx | 80 +++--- .../markdown-features-react.mdx | 251 +++--------------- 3 files changed, 72 insertions(+), 261 deletions(-) diff --git a/project-words.txt b/project-words.txt index cae0c44958fa..58e3a6b7ff1d 100644 --- a/project-words.txt +++ b/project-words.txt @@ -18,6 +18,7 @@ autoconverted autogen autogenerating autohide +autolinks backport backticks bartosz @@ -48,6 +49,7 @@ codegen codeql codesandbox codespaces +commonmark contravariance corejs crawlable diff --git a/website/docs/guides/markdown-features/markdown-features-plugins.mdx b/website/docs/guides/markdown-features/markdown-features-plugins.mdx index 1aa78617f306..b0e692a697cb 100644 --- a/website/docs/guides/markdown-features/markdown-features-plugins.mdx +++ b/website/docs/guides/markdown-features/markdown-features-plugins.mdx @@ -18,7 +18,7 @@ And the answer is: create an MDX plugin! MDX has a built-in [plugin system](http - Creating remark/rehype plugins to transform the elements generated by existing MDX syntax; - Creating remark/rehype plugins to introduce new syntaxes to MDX. -If you play with the [MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground), you would notice that the MDX transpilation has two intermediate steps: Markdown AST (MDAST), and Hypertext AST (HAST), before arriving at the final JSX output. MDX plugins also come in two forms: +If you play with the [MDX playground](https://mdxjs.com/playground/), you would notice that the MDX transpilation has two intermediate steps: Markdown AST (MDAST), and Hypertext AST (HAST), before arriving at the final JSX output. MDX plugins also come in two forms: - **[Remark](https://github.com/remarkjs/remark/)**: processes the Markdown AST. - **[Rehype](https://github.com/rehypejs/rehype/)**: processes the Hypertext AST. @@ -45,15 +45,9 @@ These are all typical use-cases of Remark plugins, which can also be a source of An MDX plugin is usually an npm package, so you install them like other npm packages using npm. Take the [math plugins](./markdown-features-math-equations.mdx) as an example. ```bash npm2yarn -npm install --save remark-math@3 rehype-katex@4 +npm install --save remark-math@5 rehype-katex@6 ``` -:::note - -There's recently a trend in the Remark/Rehype ecosystem to migrate to ES Modules, a new JavaScript module system, which Docusaurus doesn't support yet. Please make sure your installed plugin version is CommonJS-compatible before we officially support ESM. Alternatively, you can read about using dynamic `import()` as a workaround in the tutorial of installing [`rehype-katex`](./markdown-features-math-equations.mdx#upgrading-rehype-katex-beyond-recommended-version). - -::: -
How are remark-math and rehype-katex different? @@ -63,30 +57,34 @@ Next, the `rehype-katex` operates on the Hypertext AST where everything has been
-Next, add them to the plugin options through plugin or preset config in `docusaurus.config.js`: +:::caution + +Many official Remark/Rehype plugins are using ES Modules, a new JavaScript module system, which Docusaurus doesn't support yet. To work around this issue, we recommend to use dynamic `import()` inside an `async` config creation function. + +::: + +Next, add them to the plugin options through plugin or preset config in `docusaurus.config.js`, using dynamic `import()`: ```js title="docusaurus.config.js" // highlight-start -const math = require('remark-math'); -const katex = require('rehype-katex'); -// highlight-end - -module.exports = { - title: 'Docusaurus', - tagline: 'Build optimized websites quickly, focus on your content', - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - // highlight-start - remarkPlugins: [math], - rehypePlugins: [katex], - // highlight-end +module.exports = async function createConfigAsync() { + // highlight-end + return { + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + path: 'docs', + // highlight-start + remarkPlugins: [(await import('remark-math')).default], + rehypePlugins: [(await import('rehype-katex')).default], + // highlight-end + }, }, - }, + ], ], - ], + }; }; ``` @@ -95,21 +93,23 @@ module.exports = { Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like this: ```js title="docusaurus.config.js" -module.exports = { - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - remarkPlugins: [math], - rehypePlugins: [ - // highlight-next-line - [katex, {strict: false}], - ], +module.exports = async function createConfigAsync() { + return { + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + rehypePlugins: [ + // highlight-start + [(await import('rehype-katex')).default, {strict: false}], + // highlight-end + ], + }, }, - }, + ], ], - ], + }; }; ``` diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index bce7d6747600..13f9bbbcc433 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -17,14 +17,29 @@ import styles from './markdown-features-react.module.css'; Docusaurus has built-in support for [MDX v2](https://mdxjs.com/), which allows you to write JSX within your Markdown files and render them as React components. -:::note +:::info MDX vs COMMONMARK + +Docusaurus parses both `.md` and `.mdx` files using MDX, but **the syntax is interpreted differently based on the file extension**: + +- With the `.md` extension, the parser is compatible with [CommonMark](https://commonmark.org/) and does not allow the usage of JSX. +- With the `.mdx` extension, the parser is stricter than [CommonMark](https://commonmark.org/) and is not 100% compatible with it, but it becomes possible to use JSX. + +It is also possible to override the file extension format with front matter: `format: mdx`. -While Docusaurus parses both `.md` and `.mdx` files using MDX, some of the syntaxes are treated slightly differently by third-party tools. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax. +The rest of this page assumes usage of the `mdx` format. ::: Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX. +:::tip Debugging MDX + +The MDX format is quite strict, and you may get compilation errors. + +Use the **[MDX playground](https://mdxjs.com/playground/)** to debug them and make sure your syntax is valid. + +::: + ### Exporting components {#exporting-components} To define any custom component within an MDX file, you have to export it: only paragraphs that start with `export` will be parsed as components instead of prose. @@ -84,10 +99,6 @@ Since all doc files are parsed using MDX, anything that looks like HTML is actua Foo ``` -This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.mdx#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 {#importing-components} @@ -204,7 +215,7 @@ From MDX v2+ onward (Docusaurus v3+), lower-case tag names are always rendered a :::caution -This feature is powered by [a wrapper provider](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/advanced/components#mdxprovider). If you are importing Markdown in a React page, you have to supply this provider yourself through the `MDXContent` theme component. +This feature is powered by [a MDXProvider](https://mdxjs.com/docs/using-mdx/#mdx-provider). If you are importing Markdown in a React page, you have to supply this provider yourself through the `MDXContent` theme component. ```jsx title="src/pages/index.js" import React from 'react'; @@ -231,227 +242,25 @@ If you don't wrap your imported MDX with `MDXContent`, the global scope will not ### Markdown and JSX interoperability {#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** -``` - -```mdx-code-block -
-
- - -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** -``` - -```mdx-code-block -
-
- - -Use JSX for the paragraph to stop worrying about Markdown - -​← This is a zero-width space and afterwards _Markdown_ **works** - - -
- - +Docusaurus v3 is using [MDX v2](https://mdxjs.com/blog/v2/). -**Markdown within a JSX tag never works:** +The [MDX syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) is mostly compatible with [CommonMark](https://commonmark.org/), but is much stricter because your `.mdx` files are compiled into real React components (check the [playground](https://mdxjs.com/playground/)). - - -
-``` - -```jsx -**Bold doesn't work** -``` +Some valid CommonMark features won't work with MDX ([more info](https://mdxjs.com/docs/what-is-mdx/#markdown)), notably: -```mdx-code-block -
-
- +- Indented code blocks: use triple backticks instead +- Autolinks (``): use regular link syntax instead (`[http://localhost:3000](http://localhost:3000)`) +- HTML syntax (`

`) +- Unescaped `{` and `<`: escape them with `\` instead (`\{` and `\<`) -**Bold doesn't work** - - -

- - - - -Use JSX within JSX tag, or move the Markdown to the outer layer: - -
-``` - -```jsx -Bold now works - -**Bold now works** -``` - -```mdx-code-block -
-
- - -Bold now works - -**Bold now works** - - -
- - - -**Text immediately below a JSX tag will be seen as JSX text:** - - - -
-``` - -{/* prettier-ignore */} -```jsx -
-**Bold still doesn't work** -
-``` - -```mdx-code-block -
-
- - -
-**Bold still doesn't work** -
- - -
- - - -Add an empty new line: - -
-``` - -{/* prettier-ignore */} -```jsx -
- -**Bold now works** - -
-``` - -```mdx-code-block -
-
- -
- -**Bold now works** - -
- -
- - - -**Markdown text indented by four spaces will be seen as a code block:** - - - -
-``` - -{/* prettier-ignore */} -```jsx -
- - You may think I'm just some text... - -
-``` - -```mdx-code-block -
-
- - -
- - You may think I'm just some text... - -
- - -
- - - -Don't indent: - -
-``` - -{/* prettier-ignore */} -```jsx -
- -Now I'm actually just text - -
-``` +:::tip -```mdx-code-block -
-
- -
+In case you need a less strict format, with [CommonMark](https://commonmark.org/) compatibility, you can use: -Now I'm actually just text +- The `.md` file extension instead of `.mdx` +- The `format: md` front matter -
- -
- - -``` - -
+::: ## Importing code snippets {#importing-code-snippets} From 925c1c0fc5eb72aa032dff3903bb5263a50ae26c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Fri, 28 Apr 2023 14:43:10 +0200 Subject: [PATCH 2/4] Update website/docs/guides/markdown-features/markdown-features-react.mdx Co-authored-by: Balthasar Hofer --- .../docs/guides/markdown-features/markdown-features-react.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 13f9bbbcc433..4ddb47444ce9 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -250,7 +250,7 @@ Some valid CommonMark features won't work with MDX ([more info](https://mdxjs.co - Indented code blocks: use triple backticks instead - Autolinks (``): use regular link syntax instead (`[http://localhost:3000](http://localhost:3000)`) -- HTML syntax (`

`) +- HTML syntax (`

`): use JSX instead (`

`) - Unescaped `{` and `<`: escape them with `\` instead (`\{` and `\<`) :::tip From 29a186a634ed49cd7674afd5ff1263b58fa487f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Fri, 28 Apr 2023 14:43:34 +0200 Subject: [PATCH 3/4] Update website/docs/guides/markdown-features/markdown-features-react.mdx Co-authored-by: Joshua Chen --- .../docs/guides/markdown-features/markdown-features-react.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 4ddb47444ce9..2820e35c3919 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -215,7 +215,7 @@ From MDX v2+ onward (Docusaurus v3+), lower-case tag names are always rendered a :::caution -This feature is powered by [a MDXProvider](https://mdxjs.com/docs/using-mdx/#mdx-provider). If you are importing Markdown in a React page, you have to supply this provider yourself through the `MDXContent` theme component. +This feature is powered by [an `MDXProvider`](https://mdxjs.com/docs/using-mdx/#mdx-provider). If you are importing Markdown in a React page, you have to supply this provider yourself through the `MDXContent` theme component. ```jsx title="src/pages/index.js" import React from 'react'; From cde519c21fbae1e1ab16cec24c67fb1841e8c8f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Fri, 28 Apr 2023 14:43:42 +0200 Subject: [PATCH 4/4] Update website/docs/guides/markdown-features/markdown-features-react.mdx Co-authored-by: Joshua Chen --- .../docs/guides/markdown-features/markdown-features-react.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 2820e35c3919..9c1272f9a50b 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -17,7 +17,7 @@ import styles from './markdown-features-react.module.css'; Docusaurus has built-in support for [MDX v2](https://mdxjs.com/), which allows you to write JSX within your Markdown files and render them as React components. -:::info MDX vs COMMONMARK +:::info MDX vs. CommonMark Docusaurus parses both `.md` and `.mdx` files using MDX, but **the syntax is interpreted differently based on the file extension**: