mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-03 08:49:51 +02:00
docs: v3 upgrade guide should mention MDX v1 compat options (#9452)
This commit is contained in:
parent
7e456ece3c
commit
4a0bd92148
1 changed files with 64 additions and 0 deletions
|
@ -826,6 +826,70 @@ Make sure to use `remark-math 6` and `rehype-katex 7` for Docusaurus v3 (using M
|
|||
}
|
||||
```
|
||||
|
||||
### Turn off MDX v1 compat
|
||||
|
||||
Docusaurus v3 comes with [MDX v1 compatibility options](../api/docusaurus.config.js.mdx#markdown), that are turned on by default.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
export default {
|
||||
markdown: {
|
||||
mdx1Compat: {
|
||||
comments: true,
|
||||
admonitions: true,
|
||||
headingIds: true,
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### `comments` option
|
||||
|
||||
This option allows the usage of HTML comments inside MDX, while HTML comments are officially not supported anymore.
|
||||
|
||||
For MDX files, we recommend to progressively use MDX `{/* comments */}` instead of HTML `<!-- comments -->`, and then turn this compatibility option off.
|
||||
|
||||
:::info Blog truncate marker
|
||||
|
||||
The default blog truncate marker now supports both `<!-- truncate -->` and `{/* truncate */}`.
|
||||
|
||||
:::
|
||||
|
||||
#### `admonitions` option
|
||||
|
||||
This option allows the usage of the Docusaurus v2 [admonition title](../guides/markdown-features/markdown-features-admonitions.mdx#specifying-title) syntax:
|
||||
|
||||
```md
|
||||
:::note Your Title
|
||||
|
||||
content
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
Docusaurus now implements admonitions with [Markdown Directives](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) (implemented with [remark-directive](https://github.com/remarkjs/remark-directive)), and the syntax to provide a directive label requires square brackets:
|
||||
|
||||
```md
|
||||
:::note[Your Title]
|
||||
|
||||
content
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
We recommend to progressively use the new Markdown directive label syntax, and then turn this compatibility option off.
|
||||
|
||||
#### `headingIds` option
|
||||
|
||||
This option allows the usage of the Docusaurus v2 [explicit heading id](../guides/markdown-features/markdown-features-toc.mdx#heading-ids) syntax:
|
||||
|
||||
```mdx-code-block
|
||||
<Code language="md">{'### Hello World \u007B#my-explicit-id}\n'}</Code>
|
||||
```
|
||||
|
||||
This syntax is now invalid MDX, and would require to escape the `{` character: `\{#my-explicit-id}`.
|
||||
|
||||
We recommend to keep this compatibility option on for now, until we provide a new syntax compatible with newer versions of MDX.
|
||||
|
||||
## Ask For Help
|
||||
|
||||
In case of any upgrade problem, the first things to try are:
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue