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

website/docs/migration/v3.mdx

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