Hi all,
I am planning on upgrading the Druid website to Docusaurus 3.10. We're
currently on an earlier version of 3. This impacts two Druid repos
(apache/druid and apache/druid-website-src). 3.10 is the last planned
release before 4.0, so we should be able to stay on it for a bit until we
(and the plugin ecosystem) are ready.
On a day-to-day basis, 3.10 will change the following things about
contributing to the docs:
* Prefer Markdown eXtended (.mdx) file format instead of Markdown (.md).
Currently, Docusaurus silently converts .md to .mdx in the background. The
developers are encouraging people to switch where appropriate. I think it's
easier for us to just bulk `git mv` the files from .md to .mdx and set the
expectation that people use .mdx in the future since it provides a wider
feature set.
* In .mdx files, HTML comments (<!-- COMMENT -->) are replaced with
MDX/Javascript comments ({/* COMMENT */}).
The upgrade has the following one-time impact:
* The minimum node version is now 22.
* Users who want to build the docs for local preview or production need to
install the upgrade, e.g. `yarn install`, after the PR is merged.
Additionally, I'll enable the `faster` flag that speeds up builds.
Once the upgrade to 3.10 is done, we can start toggling the
preview/backwards compatibility flags that are in 3.x,. This way, when we
do upgrade, there shouldn't be any major hurdles.
One known impact for 4.0 is that it changes how CSS is handled (
https://docusaurus.io/fr/blog/releases/3.8#css-cascade-layers). It may
break some of our styling, so we'll want to test/fix on 3.10 using the
compatibility flags instead of doing it during the 4.0 upgrade.
Best,
Brian
