3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-04-29 18:27:56 +02:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source 
* 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 <sidachen2003@gmail.com>

* docs: Update MDX version

* Update website/docs/migration/v3.mdx

* Update v3.mdx

---------

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
This commit is contained in:
Tatsunori Uchino 2023-11-24 03:38:04 +09:00 • committed by GitHub
parent 8dc24b6a98
commit 6cc29fac01
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 21 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
website/docs/guides/markdown-features/markdown-features-react.mdx
View file

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

15
website/docs/migration/v3.mdx
View file

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