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..9c1272f9a50b 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 [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';
@@ -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 aboutMarkdown
-
-← This is a zero-width space and afterwards _Markdown_ **works**
-```
-
-```mdx-code-block
-
-
-
-
-Use JSX for the paragraph to stop worrying aboutMarkdown
-
-← 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 (`
`): use JSX instead (`
`)
+- 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
-