From 6cc29fac010b7dc4a92ccfdc5133a9d85ef2dac4 Mon Sep 17 00:00:00 2001 From: Tatsunori Uchino Date: Fri, 24 Nov 2023 03:38:04 +0900 Subject: [PATCH] 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 * docs: Update MDX version * Update website/docs/migration/v3.mdx * Update v3.mdx --------- Co-authored-by: Joshua Chen --- .../markdown-features/markdown-features-react.mdx | 6 ++++++ website/docs/migration/v3.mdx | 15 +++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 1aa05ba173..c5eeb237bc 100644 --- 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 index 6ee782d98e..b6ef805de8 100644 --- 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 */} +Some long text in the component +``` + +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.