docs: add heads up for Prettier users (#9471)

* docs: add a note on the use of Prettier for MDX * docs: add guides for Prettier users migrating to v3 * Update website/docs/guides/markdown-features/markdown-features-react.mdx Co-authored-by: Joshua Chen <[email protected]> * docs: Update MDX version * Update website/docs/migration/v3.mdx * Update v3.mdx --------- Co-authored-by: Joshua Chen <[email protected]>
facebook · Nov 23, 2023 · 6cc29fa · 6cc29fa
1 parent 8dc24b6
commit 6cc29fa
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 0 deletions.
diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx
@@ -25,6 +25,12 @@ Use the **[MDX playground](https://mdxjs.com/playground/)** to debug them and ma
 
 :::
 
+:::info
+
+Prettier, the most popular formatter, [supports only the legacy MDX v1](https://github.com/prettier/prettier/issues/12209). If you get an unintentional formatting result, you may want to add `{/* prettier-ignore */}` before the problematic area, or add `*.mdx` to your `.prettierignore`, until Prettier has proper support for MDX v3. [One of the main authors of MDX recommends `remark-cli` with `remark-mdx`](https://github.com/orgs/mdx-js/discussions/2067).
+
+:::
+
 ### 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.

diff --git a/website/docs/migration/v3.mdx b/website/docs/migration/v3.mdx
@@ -464,6 +464,21 @@ If you created custom Remark or Rehype plugins, you may need to refactor those,
 
 :::
 
+### Formatters
+
+Prettier, the most common formatter, supports only the legacy MDX v1, not v3 yet as of Docusaurus v3.0.0. You can add `{/* prettier-ignore */}` before the incompatible parts of your code to make it work with Prettier.
+
+```mdx
+{/* prettier-ignore */}
+<SomeComponent>Some long text in the component</SomeComponent>
+```
+
+If you get tired of too many `{/* prettier-ignore */}` insertions, you can consider disabling MDX formatting by Prettier by adding the following to your `.prettierignore` file, until it starts supporting MDX v3:
+
+```txt title=".prettierignore"
+*.mdx
+```
+
 ## Other Breaking Changes
 
 Apart the MDX v3 upgrade, here is an exhaustive list of breaking changes coming with Docusaurus v3.
-Original file line number
+Diff line change
@@ Expand Up @@
     :::
+    :::info
+    Prettier, the most popular formatter, [supports only the legacy MDX v1](https://github.com/prettier/prettier/issues/12209). If you get an unintentional formatting result, you may want to add `{/* prettier-ignore */}` before the problematic area, or add `*.mdx` to your `.prettierignore`, until Prettier has proper support for MDX v3. [One of the main authors of MDX recommends `remark-cli` with `remark-mdx`](https://github.com/orgs/mdx-js/discussions/2067).
+    :::
     ### 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.
@@ Expand Down @@