From b6ca18bf0a115c238ac6bd9d4288e5822a600f41 Mon Sep 17 00:00:00 2001 From: Tatsunori Uchino Date: Wed, 18 Oct 2023 23:32:21 +0900 Subject: [PATCH 1/6] docs: add a note on the use of Prettier for MDX --- .../markdown-features/markdown-features-react.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 1aa05ba1734d..ac1eb71480ce 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -25,6 +25,20 @@ 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 format result, you may want to add `{/* prettier-ignore */}` before the problem area. + +If you are fed up with inserting `{/* prettier-ignore */}` in too many places, you can consider to disable formatting MDX by Prettier by creating the following `.prettierignore` until it starts supporting MDX v2: + +``` +*.mdx +``` + +[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. From 3c0b0446f42d2bd6ff63757d17e0253c1f9eefb6 Mon Sep 17 00:00:00 2001 From: Tatsunori Uchino Date: Fri, 27 Oct 2023 01:05:50 +0900 Subject: [PATCH 2/6] docs: add guides for Prettier users migrating to v3 --- website/docs/migration/v3.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/website/docs/migration/v3.mdx b/website/docs/migration/v3.mdx index a93b6fcd106c..c94e72b4ffb6 100644 --- a/website/docs/migration/v3.mdx +++ b/website/docs/migration/v3.mdx @@ -464,6 +464,23 @@ 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 v2 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 creating the following `.prettierignore` in the project root until it starts supporting MDX v2: + +```txt title=".prettierignore" +*.mdx +``` + +If you have already created `.prettierignore` before, you can append the above line to it. + ## Other Breaking Changes Apart the MDX v3 upgrade, here is an exhaustive list of breaking changes coming with Docusaurus v3. From c03ebe23ff6bfc010e97834dcd6a6e19a4c865ec Mon Sep 17 00:00:00 2001 From: Tatsunori Uchino Date: Mon, 30 Oct 2023 23:38:01 +0900 Subject: [PATCH 3/6] Update website/docs/guides/markdown-features/markdown-features-react.mdx Co-authored-by: Joshua Chen --- .../markdown-features/markdown-features-react.mdx | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index ac1eb71480ce..0eabe5aad6b6 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -27,15 +27,7 @@ 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 format result, you may want to add `{/* prettier-ignore */}` before the problem area. - -If you are fed up with inserting `{/* prettier-ignore */}` in too many places, you can consider to disable formatting MDX by Prettier by creating the following `.prettierignore` until it starts supporting MDX v2: - -``` -*.mdx -``` - -[One of the main authors of MDX recommends `remark-cli` with `remark-mdx`](https://github.com/orgs/mdx-js/discussions/2067). +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 v2. [One of the main authors of MDX recommends `remark-cli` with `remark-mdx`](https://github.com/orgs/mdx-js/discussions/2067). ::: From f13b3618b152fa25c160fe1064a629e34bd79bdc Mon Sep 17 00:00:00 2001 From: Tatsunori Uchino Date: Mon, 30 Oct 2023 23:47:09 +0900 Subject: [PATCH 4/6] docs: Update MDX version --- .../docs/guides/markdown-features/markdown-features-react.mdx | 2 +- website/docs/migration/v3.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 0eabe5aad6b6..c5eeb237bc7d 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -27,7 +27,7 @@ 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 v2. [One of the main authors of MDX recommends `remark-cli` with `remark-mdx`](https://github.com/orgs/mdx-js/discussions/2067). +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). ::: diff --git a/website/docs/migration/v3.mdx b/website/docs/migration/v3.mdx index c94e72b4ffb6..94a9205335dc 100644 --- a/website/docs/migration/v3.mdx +++ b/website/docs/migration/v3.mdx @@ -466,7 +466,7 @@ 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 v2 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. +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 */} From 453b7097b4c2a794ba58bfab1948b48a49cbf943 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 23 Nov 2023 13:27:07 -0500 Subject: [PATCH 5/6] Update website/docs/migration/v3.mdx --- website/docs/migration/v3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/migration/v3.mdx b/website/docs/migration/v3.mdx index 94a9205335dc..c8706bc78c8d 100644 --- a/website/docs/migration/v3.mdx +++ b/website/docs/migration/v3.mdx @@ -473,7 +473,7 @@ Prettier, the most common formatter, supports only the legacy MDX v1, not v3 yet 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 creating the following `.prettierignore` in the project root until it starts supporting MDX v2: +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`, until it starts supporting MDX v3: ```txt title=".prettierignore" *.mdx From 43fee3c7645b81609921299bc372b79b6b45f72e Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 23 Nov 2023 13:27:32 -0500 Subject: [PATCH 6/6] Update v3.mdx --- website/docs/migration/v3.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/website/docs/migration/v3.mdx b/website/docs/migration/v3.mdx index c8706bc78c8d..bd0bf351e26c 100644 --- a/website/docs/migration/v3.mdx +++ b/website/docs/migration/v3.mdx @@ -473,14 +473,12 @@ Prettier, the most common formatter, supports only the legacy MDX v1, not v3 yet 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`, until it starts supporting MDX v3: +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 ``` -If you have already created `.prettierignore` before, you can append the above line to it. - ## Other Breaking Changes Apart the MDX v3 upgrade, here is an exhaustive list of breaking changes coming with Docusaurus v3.