disable vscode formatting for mdx files

[dario-piotrowicz]

Since formatOnSave is enabled by default, whenever I save an MDX file I get vscode formatting the file, this would generally be ideal, the problem being that the formatting is pretty broken, if the file contains any js/ts snippet the indentation of those gets completely broken, three backticks also get added at the end of the MDX files and I am pretty sure that I noticed other weird results as well.

So as far as I can tell formatting on the MDX files doesn't really work, thus why I am proposing to disable it here.

(Currently the way I work around the current broken formatting is by disabling temporarily formatOnSave or saving without formatting via the command palette, neither is really ideal)

I have seen this issue occur to other people other than me so I am making the assumption that this is a general issue, if not and there is some configuration that I am missing on my machine please let me know 🙂

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
*	@cloudflare/pcx-technical-writing

[github-actions]

Preview URL: https://4fda6c8d.preview.developers.cloudflare.com
Preview Branch URL: https://dario-no-formatter-for-vscode-mdx.preview.developers.cloudflare.com

[pedrosousa]

I've been able to work around the few issues I found with Prettier and formatOnSave, either by adding some newlines or by prettier-ignoring some pieces of MDX content.

Having said that, I know that not everyone likes having Prettier enabled together with formatOnSave, regardless of the file type. Prettier is very opinionated and it fails in more complex situations (namely in MDX).

We're having internal discussions about alternative formatters and their settings (CC @maxvp).

In my opinion, for the time being it would be preferable to remove both formatOnSave and editor.defaultFormatter settings from workspace settings (committed to the repo) rather than imposing a null formatter for MDX. (Another possibility would be to just remove formatOnSave.) By not having a workspace setting, we could eventually be less consistent for now, but we would also be less prescriptive (which is causing some frustration with Prettier). Users would be able to set their preferred settings at the user level instead of workspace level (we could still have recommendations).

When we have done our research on formatters, we could revisit the possibility of having these settings back at the workspace level.

[dario-piotrowicz]

@pedrosousa your idea sounds good to me 🙂

I don't personally see prettier being opinionated as an issue, the problem here for me is that it actually applies changes that are objectively incorrect and having to always try to prevent it from doing so and/or revert such changes is quite cumbersome in my opinion.

So as long as we can avoid that I'm happy 😄

Shall I close this PR for now then?

[maxvp]

Hi @dario-piotrowicz, seconding what @pedrosousa said about imposing a null formatter.

One solution our team has found for problematic formatting is surrounding text in your MDX file with {/* prettier-ignore-start */} and {/* prettier-ignore-end */}. This forces your local Prettier extension to ignore anything between the tags and doesn't have any implications in the final MDX render.

[dario-piotrowicz]

Hi @dario-piotrowicz, seconding what @pedrosousa said about imposing a null formatter.

One solution our team has found for problematic formatting is surrounding text in your MDX file with {/* prettier-ignore-start */} and {/* prettier-ignore-end */}. This forces your local Prettier extension to ignore anything between the tags and doesn't have any implications in the final MDX render.

Are you suggesting to add and commit {/* prettier-ignore-start */} and {/* prettier-ignore-end */} for MDX files and include them in PRs? that seems quite cumbersome and prone to create a bunch of extra noise / tech debt, instead of disabling the thing in a single centralized place 🤔

(If you are insted suggesting to add the blocks only during development and not commit them... well, I don't think that that would be super convenient either and I might as well just stick with my current workarounds 😕)

[maxvp]

Hi @dario-piotrowicz, seconding what @pedrosousa said about imposing a null formatter.
One solution our team has found for problematic formatting is surrounding text in your MDX file with {/* prettier-ignore-start */} and {/* prettier-ignore-end */}. This forces your local Prettier extension to ignore anything between the tags and doesn't have any implications in the final MDX render.

Are you suggesting to add and commit {/* prettier-ignore-start */} and {/* prettier-ignore-end */} for MDX files and include them in PRs? that seems quite cumbersome and prone to create a bunch of extra noise / tech debt, instead of disabling the thing in a single centralized place 🤔

(If you are insted suggesting to add the blocks only during development and not commit them... well, I don't think that that would be super convenient either and I might as well just stick with my current workarounds 😕)

The technical writing team has been using the tags, but most of us are using Prettier within a local VS Code environment. If you're not working in the docs as often, this probably isn't necessary.

PCX is still working through the issue of formatting for now -- work is being tracked with PCX-14600. I think we can close this PR in the meantime.