[WIP] Upgrade to Docusaurus 3

[Mercurial]

[katomm]

Hey Clark, great to see you. Can we briefly discuss beforehand if we want to go through another beta update hell with the portal and have constant UI and other breaking changes likely?

[Mercurial]

Hey Clark, great to see you. Can we briefly discuss beforehand if we want to go through another beta update hell with the portal and have constant UI and other breaking changes likely?

for sure, thats why this is just a draft to start that process, infact we can merge this PR once v3 is released to ensure stability and just keep track of the beta and make sure the portal is ready for the release

[katomm]

Docusaurus 3.0 RC is out https://github.com/facebook/docusaurus/discussions/9429

it felt like the beta had just launched.

[Mercurial]

Let's goo, time get my hands dirty 😅. Will check what compatibility issues needs to be fixed

[Mercurial]

After looking further, heres a list of compatiblity issues I've found so far.

• The changelog-plugin is incompatible and will need to be updated, it seems to be looking for files under developer-portal/.docusaurus/docusaurus-plugin-content-blog/changelog/ but the actual files are in developer-portal/.docusaurus/changelog-plugin/default
• MDX parser is much more strict now and complaints when parsing the CIP markdown files For example this section:

#### Calculate the change to send back to `payment.addr`

All amounts must be in Lovelace:

   expr <UTXO BALANCE> - <AMOUNT TO SEND> - <TRANSACTION FEE>

The parser thinks it <TRANSACTION FEE> should have a closing tag.

Could be a good oppurtunity to rewrite the CIP into a blog content plugin-aswell. That way we can display the authors much more clearly since the blog already has support for that.

P.S this is by no means a comprehensive list of compatiblity issues

[rphair]

@Mercurial @katomm if we could suppress the interpretation of opening tags it would be a big help to the CIP process. As it is now, we've had to make more changes like these to stop headers from being wiped out after the first < character:

• https://github.com/cardano-foundation/CIPs/pull/591
• https://github.com/cardano-foundation/CIPs/pull/601

... which has been OK so far, since we've cleaned up the formatting of code segments used as document headers, but over time would have to enforce this in every bit of pseudocode like the above... which would be a full-time job. 😰

[katomm]

@fill-the-fill could you please look into the points that @Mercurial raised above?

[rphair]

@katomm @Mercurial it's out of RC! 🤓 Just seen tonight in local build: Update available 2.4.3 → 3.0.1

[katomm]

@fill-the-fill or @Mercurial did not answer yet, so clever to put this on hold for now. (In particular before Christmas)

[rphair]

@katomm @fill-the-fill @Mercurial newer version ready now 🤠🚀

Update available 2.4.3 → 3.1.0

[katomm]

@fill-the-fill, six months passed, any opinion on this? Thanks

[katomm]

Hate to be the guy, but can we please get an answer here @fill-the-fill

[rphair]

another advantage to upgrading: to fix some outdated packages likely not reconcilable with the current Docusaurus version's package configuration, e.g. (observable in local build):

Browserslist: caniuse-lite is outdated. Please run:
  npx update-browserslist-db@latest
  Why you should do it regularly: https://github.com/browserslist/update-db#readme

[fill-the-fill]

Fixed it in #1335

[rphair]

I think it's OK to close this since we have a working build in the other PR (all that remains to be fixed are build warnings & apparently some artefacts from content reformatting: since many reported errors aren't in the source material). @Mercurial I hope you can double-check my last https://github.com/cardano-foundation/developer-portal/pull/1335#pullrequestreview-2351694783 & my hypothesis about what the problem might be.