Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 1 commit into from
Oct 26, 2023
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
64 changes: 64 additions & 0 deletions website/docs/migration/v3.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down