Add warning about Prettier/plain Markdown formatters in Docs about MDC syntax

[nwittwer]

Is your feature request related to a problem? Please describe

After installing the MDC VSCode extension and trying to re-write my .md files with the MDC syntax (moving from @nuxt/content v1 to v2), it was frustrating to try writing MDC, save, and then the code is re-formatted back to Markdown format.

The reason: I'm using Prettier for code formatting, and because the file is .md (just like normal Markdown), it has no way to know I want to use MDC syntax. Prettier's Parser automatically enables formatting on .md files.

Example (before: default Prettier, after: disabled Prettier on .md files w/ .prettierignore)

Describe the solution you'd like

The Docs currently only mention installing the VSCode extension:

Install the MDC VS Code extension to get proper syntax highlighting for your MDC components.

Likely there are others who will upgrade to Content v2, are using Prettier, and will encounter a similar issue with .md be re-formatted. I know this is not really an issue on the Nuxt ecosystem side. But maybe the Docs can mention a warning about it, to make things as smooth as possible. Even better would be if the Nuxt MDC VSCode extension could provide MDC formatting, but probably that would take more time to figure out.

Suggestion: Add at least one sentence to the Docs that some additional configuration may be needed to tell VSCode which formatter to use, so that MDC is properly formatted instead of using Markdown formatting.

For example:

Install the MDC VS Code extension to get proper syntax highlighting for your MDC components.
⚠️ If you use Prettier or other code formatting extensions, see this section so your .md files with MDC syntax won't be automatically re-formatted to plain Markdown.

And a more detailed description section it links to:

Disable Markdown formatting on MDC written in.md files

Prettier and other code formatting extensions will try to format .md files to plain Markdown and not the MDC syntax. As a workaround, you can disable automatic Markdown formatting for all of the .md files where you'd like to use MDC syntax and not plain Markdown.

• Prettier: If you're using MDC for all your .md files, create a .prettierignore file and add a new line: *.md to disable Prettier for all Markdown files. You could also configure only certain paths, e.g. /blog/**/*.md if you have some files that you'd still like to format with plain Markdown. Refer to Prettier docs.

Describe alternatives you've considered

1. There's an open ticket on Prettier to add MDC syntax: [Markdown] Markdown components (MDC) syntax support prettier/prettier#13512. Maybe in the future there will be an easier way to indicate that an .md file is using MDC syntax and not plain Markdown?
2. Or the Nuxt MDC VSCode extension could have its own MDC formatter which tries to override other formatters the user has installed?
3. Or a new dedicated .mdc extension like the MDX format (.mdx) could make it easier to distinguish whether the file should be parsed as plain Markdown, MDC, etc.

[Tahul]

Hey @nwittwer ; I already encountered this problem too, thank you a lot for reporting it so clearly.

@Atinux @farnabaz what are your insights?

That is something I think we should look at, at least at for a documentation section, at best a feature in MDC extension, or @nuxt/content itself?

[farnabaz]

I think we can overwrite prettier's markdown parser to use remark/mdc.
We need to research a bit prettier markdown plugin and parser. I'm not very familiar with prettier, and don't know if there is any extra markdown plugins for prettier markdown parser.
If there isn't any we can simply replace default parser with our own parser to support MDC syntax.

[fanckush]

is there a workaround for this atm?