Docusaurus v3 upgrade

[kcpevey]

This PR upgrades the docs to Docusaurus V3. There are some breaking changes and this PR includes all the required changes to make the docs build again after the upgrade.

Some things to note:

• the icon admonition we had in the docusaurus config is no longer allowed. I had a hard time understanding the admonitions, but it seems like the icon admonition was being customized in /src/theme/components/admonitions.scss and the examples for V3 are all using js. Those are outside of my skillset so if we want to keep that, I'll need some help with that bit.
• I'm not very familiar with yarn, but I followed the directions to upgrade all the packages and update the package.json and yarn.lock. I think I did that right?
• A lot of the required updates were around links. While I was fixing the link syntax, if the link was not accessible (i.e. was just underneath the word "here"), I reworded the text so the link text would be more descriptive. That is only reason for the wording changes in this PR.

Reference Issues or PRs

Resolves #395

What does this implement/fix?

Put a x in the boxes that apply

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds a feature)
• Breaking change (fix or feature that would cause existing features not to work as expected)
• Documentation Update
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no API changes)
• Build related changes
• Other (please describe):

Testing

• Did you test the pull request locally?
• Did you add new tests?

Documentation

Access-centered content checklist

Text styling

• The content is written with plain language (where relevant).
• If there are headers, they use the proper header tags (with only one level-one header: H1 or # in markdown).
• All links describe where they link to (for example, check the Nebari website).
• This content adheres to the Nebari style guides.

Non-text content

• All content is represented as text (for example, images need alt text, and videos need captions or descriptive transcripts).
• If there are emojis, there are not more than three in a row.
• Don't use flashing GIFs or videos.
• If the content were to be read as plain text, it still makes sense, and no information is missing.

Any other comments?

[netlify]

✅ Deploy Preview for nebari-docs ready!

Name	Link
🔨 Latest commit	d1e9cd6
🔍 Latest deploy log	https://app.netlify.com/sites/nebari-docs/deploys/66eb194f35e7a90008e11b71
😎 Deploy Preview	https://deploy-preview-503--nebari-docs.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 configuration.

[kcpevey]

Can I get some help debugging the failure in the CI build?

The error is The engine "node" is incompatible with this module. Expected version ">=18.0". Got "16.20.2" but I've specified node>18 here. It builds fine on my machine so I think it must be something to do with the CI runner but I dont know enough about npm/yarn to sort it out.

[pavithraes]

Checked Netlify per @krassowski suggestions, and we do configure the Node version there. Updated to use 18.x now:

Re-built the site, and seems to be working on Netlify now. The preview above also works.

I am not sure why the GitHub CI is still red and not updating. @kcpevey I'll push an empty commit to this PR to re-trigger CI. Please let me know if you'd like me to refrain from pushing up to your branch in the future. :)

[kcpevey]

Please let me know if you'd like me to refrain from pushing up to your branch in the future.

I'll take all the help I can get - I always welcome collaboration :)

Thank you so much for looking into this @pavithraes ! And thanks for the assistance on finding the solution @krassowski !

[kcpevey]

This is now ready for review.

One thing that I do need resolved is the icon admonition (discussed in the description). If we're fine to remove, then its done. If it needs to stay, then I'll need help re-implementing it in a way that docusaurus v3 likes.

[kcpevey]

I removed the icon admonition as I think its no longer necessary. This is ready for review.

[viniciusdc]

nice! Thanks @kcpevey this will likely be the last in the order of merges after your #502 and #476

[kcpevey]

I'll have to do conflict resolution again whenever we are close to merging.

[viniciusdc]

Hi @kcpevey as #502 what's the status on this PR, is it ready for review?

[kcpevey]

@viniciusdc Now that blocking PR has been merged, I'll resolve conflicts and get things working again. I'll ping you when its ready for final review.

[kcpevey]

@viniciusdc this is ready for a final look!

[viniciusdc]

@kcpevey I've noticed from the current built version of this PR, that some of the admonition colors and codeblocks styles are not showing up correctly, is this intended?

before:

current PR build:

[kcpevey]

I've noticed from the current built version of this PR, that some of the admonition colors and codeblocks styles are not showing up correctly, is this intended?

Hmmm. I'll have to look more closely. I did make a change to admonitions that may be having an effect here.

[kcpevey]

@viniciusdc The styling that was previously working for the admonitions is no longer being used. All of the admonitions now are using the css rules that start with alert (e.g. even for note). So the current rules are not applied.

There is also a comment in admonitions.scss about alerts. I played with this a bit, but the behavior seems to have changed and/or I dont have the skillz needed to sort it out.

So at this point, everything in admonitions.scss is being ignored and we are just getting the default admonition styling. I'm not sure if there is anyone available to spend the time to sort this out right now.

[viniciusdc]

Thats okay thank you for having a look into it @kcpevey -- wonder if this might be due to docssaurus-sass plug-in

[kcpevey]

wonder if this might be due to docssaurus-sass plug-in

Its possible?

We brought up the plan to open an issue to resolve the admonition styling in a separate issue/PR and go ahead and merge this one since its so big. No one disagreed, so @viniciusdc I think we're good to go ahead and merge?