Format code blocks during build for consistent styling

[lforst]

In the past, we had prettier in the repo which had the positive side effect that all (JS) code blocks in the docs had consistent formatting. Since we identified that prettier does not work well with current MDX we will lose this benefit.

However, It should be possible to format the code blocks during build, regardless of the input. With this I don't mean to actually modify commited code, but to sortof transpile the code blocks during the build, so that they are displayed formatted on the website.

We could apply different formatters for different languages and we may even use prettier for the JS code blocks.

[a-hariti]

I spent some time exploring this. We can walk the AST tree and change the content of nodes as desired.

Unfortunately the current Prettier is async. The MDX pipeline assumes the visitor walking the AST to be synchronous and does not wait for Promises to resolve.

The other option is to simply use Prettier directly. Although it takes about 17 seconds to go over all the docs on my M1 mac and will include a lot of diff noise on a dozen files on the first run.

worth the tradeoff @stephanie-anderson @lforst ?

[lforst]

The other option is to simply use Prettier directly. Although it takes about 17 seconds to go over all the docs on my M1 mac and will include a lot of diff noise on a dozen files on the first run.

As mentioned in the issue, we ran into issues when running prettier on .mdx files so it is unfortunately not an option.

https://prettier.io/docs/en/api.html says

Our public APIs are all asynchronous, if you must use synchronous version for some reason, you can try @prettier/sync.

So can we try and use @prettier/sync?

[a-hariti]

I tried. It's not a quality port of Prettier

It's trying to make async functions synchronous after the fact by running them inside workers using a third party package.

It made my server just hang, not sure if it's a viable option.

[lforst]

Ok we might be blocked here then. I am still a bit sus that MDX really doesn't allow for async visiting...

[a-hariti]

@lforst I found a way 🥳, an example in an obscure issue

We can use Prettier for almost all languages using community plugins.

We need to iron out some details:

1. Error handling: what happens if prettier throws an error for whatever reason as when encountering invalid syntax?

2. Some plugins assume existence of language tooling on host machine like ruby, requiring everybody to have tooling for everything is not ideal. Choosing to do formatting on Vercel b every necessary tooling on the build machine will solve this issue but might introduce a slow feedback loop on related errors and is inconvenient for participants outside of Sentry.

Maybe we should proceed with formatting languages supported out of the box or with a pure JS plugin first?

CC @stephanie-anderson @mjq-sentry

Also who should we ask on issues related to: Java/Kotlin, Rust and Ruby

[lforst]

We can use Prettier for almost all languages using community plugins.

As a POC let's only run formatting for JS/TS(X) code blocks! These are the most frequented pages.

Error handling: what happens if prettier throws an error for whatever reason as when encountering invalid syntax?

I vote we print a warning, bail from formatting that particular code block, but do not crash the build. Sometimes we may intentionally have technically broken code and not being able to deploy that would be annoying.

Some plugins assume existence of language tooling on host machine like ruby, requiring everybody to have tooling for everything is not ideal.

Let's not worry about other langs for now.

[lforst]

Btw

I found a way 🥳, an example in an obscure issue

Nice 👌

[a-hariti]

what about a noformat meta flag to explicitly opt out of formatting?

[lforst]

what about a noformat meta flag to explicitly opt out of formatting?

Also sounds good but maybe let's do that as a followup.