3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-08-03 08:49:51 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: v3 upgrade guide should mention MDX v1 compat options (#9452)

Browse source
This commit is contained in:
Sébastien Lorber 2023-10-26 15:58:37 +02:00 • committed by GitHub
parent 7e456ece3c
commit 4a0bd92148
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 64 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

64
website/docs/migration/v3.mdx
View file

@ -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: