Major docs overhaul (remove asciidoc and switch to MDX)

[gdams]

Description of change

This is a pretty large PR so apologies in advance. In short I've ripped asciidoc out of the website and switched to MDX as it's much better supported by all the Gatsby plugins (especially i18n solutions).

Checklist

• npm test passes
• documentation is changed or added (if applicable)
• permission has been obtained to add new logo (if applicable)
• contribution guidelines followed here

[netlify]

✅ Deploy Preview for eclipsefdn-adoptium ready!

Name	Link
🔨 Latest commit	be12c74
🔍 Latest deploy log	https://app.netlify.com/sites/eclipsefdn-adoptium/deploys/63ca858f227c930009be2ab8
😎 Deploy Preview	https://deploy-preview-1397--eclipsefdn-adoptium.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[codecov]

Codecov Report

Merging #1397 (be12c74) into main (be94893) will increase coverage by 0.27%.
The diff coverage is 99.56%.

@@            Coverage Diff             @@
##             main    #1397      +/-   ##
==========================================
+ Coverage   92.21%   92.49%   +0.27%     
==========================================
  Files          78       82       +4     
  Lines        5496     5647     +151     
  Branches      476      507      +31     
==========================================
+ Hits         5068     5223     +155     
+ Misses        428      424       -4     

Impacted Files	Coverage Δ
src/hooks/useCopyToClipboard.tsx	93.33% <93.33%> (ø)
src/__fixtures__/page.tsx	100.00% <100.00%> (ø)
src/components/CodeBox/InlineCode.tsx	100.00% <100.00%> (ø)
src/components/CodeBox/index.tsx	100.00% <100.00%> (ø)
src/components/EditLink/index.tsx	100.00% <100.00%> (ø)
src/components/InstallTabs/index.tsx	100.00% <100.00%> (ø)
src/components/LanguageSelector/index.tsx	100.00% <100.00%> (+2.66%)	⬆️
src/components/SplitView/index.tsx	100.00% <100.00%> (ø)
src/pages/blog.tsx	100.00% <100.00%> (+2.80%)	⬆️
src/pages/members.tsx	100.00% <100.00%> (ø)
... and 10 more

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[karianna]

What sort of challenges were we seeing with Asciidoc and gatsby? This seems like a pretty extreme solution...

[gdams]

What sort of challenges were we seeing with Asciidoc and gatsby? This seems like a pretty extreme solution...

It's mainly the gatsby transformer plugins that don't play nicely with asciidoc. A lot of problems were caught with the recent Gatsby 5.x migration that required me to write a whole load of custom plugins that aren't going to be easy to maintain. We also introduced MDX when we merged the blog into the main website so having two different languages in a single website feels a little strange.

[karianna]

I'm not MDX expert, but the cut over seems sane

[tellison]

Thanks for this substantial piece of work! A number of comments in-lied, but overall looking good.

One theme was the handling of superscript and (e.g. code) annotations - would be good to have an md equivalent for those. The HTML handling for the buttons page made me feel a bit ill too ;-) Otherwise a fair recreation of what we have. We might choose to tweak a few pieces when the basic framework is in place.

May be best to wait until the rease rush is past before merging and finding any problems.

[gdams]

One theme was the handling of superscript and (e.g. code) annotations - would be good to have an md equivalent for those. The HTML handling for the buttons page made me feel a bit ill too ;-) Otherwise a fair recreation of what we have. We might choose to tweak a few pieces when the basic framework is in place.

Thanks @tellison, weirdly MDX should handle superscript so I've raised a bug to understand why it's not rendering on our website. Other than that the buttons page also made me feel a bit 'meh'. One of the advantages of MDX is that we can write our own custom components so I might make a side-by-side component that would allow us to mimic what we had in asciidoc.

[ascheman]

Uh, I was happy to see many docs written in asciidoc. I'd appreciate to stay with it, from my point of view it is much more powerful than Markdown, in particular if it comes to developer documentation.

Maybe you would like to re-think the choice of gatsby as microsite tool, despite dropping asciidoc? Are design/site architecture decisions like this documented somewhere? I'd like to understand what particular requirements led to such decisions.

[gdams]

Uh, I was happy to see many docs written in asciidoc. I'd appreciate to stay with it, from my point of view it is much more powerful than Markdown, in particular if it comes to developer documentation.

@ascheman remember we're not dropping it for markdown but rather MDX which is much more powerful than asciidoc. For starters, we can write custom components for pretty much anything that markdown is missing. I'm happy to have more conversations around this but from experience to date, asciidoc is not as well supported in Gatsby, often more complex when trying to do simple things (tables and code blocks for example) and less familiar to the GitHub cohort of regular contributors that make changes to our project.

[ascheman]

Uh, I was happy to see many docs written in asciidoc. I'd appreciate to stay with it, from my point of view it is much more powerful than Markdown, in particular if it comes to developer documentation.

@ascheman remember we're not dropping it for markdown but rather MDX which is much more powerful than asciidoc. For starters, we can write custom components for pretty much anything that markdown is missing. I'm happy to have more conversations around this but from experience to date, asciidoc is not as well supported in Gatsby, often more complex when trying to do simple things (tables and code blocks for example) and less familiar to the GitHub cohort of regular contributors that make changes to our project.

Well, my mileage varies on this. For instance, I prefer AsciiDoc tables over MD tables. On the one hand they are slightly harder to create (I leave that to the IntelliJ AsciiDoctor plugin) and to maintain. On the other hand they are way more powerful, e.g., if it comes to sub tables.

If it comes to more complex stuff you want to express, you always have to learn one way or the other how to do that in your given tool context. Maybe people are more used to MD at first sight. But what does it help if they have to learn MDX and Gatsby to write elaborated docs.

I am not familiar with Gatsby, but it seems to be based on TypeScript and NPM?
So folks contributing to the docs may end up having to learn that? I'd like to argue to stay in the Java world here, e.g., by using jbake (or something similar) which makes use of template engines from the JVM universe.

I mean, in the end, the Adoptium web page is a statically rendered site. What makes Gatsby the tool of choice over other alternatives? Did you consider JVM based alternatives?

Having said that, I am always happy to get a deep insight into other universes besides the Java world :-)

[karianna]

@gdams Will need a rebase