feat: versioned docs dropdown

[fykaa]

closes #3171

This pull request implements a version dropdown in the Docusaurus configuration (docusaurus.config.js) to support versioned documentation. The following changes were made:

1. Added version dropdown to Navbar:

   • Updated docusaurus.config.js to include a docsVersionDropdown in the navbar letting users to switch between different doc versions

2. Versioned doc creation:

   • Ran npm run docusaurus docs:version <version> for each version (1.0, 1.1) to generate versioned docs.
   • Updated the versions.json file to include the new versions.

Next Steps: update release procedure

• To maintain the latest doc with each minor/ patch update, the process of running npm run docusaurus docs:version <version> should be added to the release procedures

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	fb61a6b
🔍 Latest deploy log	https://app.netlify.com/sites/docs-kargo-io/deploys/677e6fad97ac150008db13df
😎 Deploy Preview	https://deploy-preview-3226.docs.kargo.io
📱 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.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 51.40%. Comparing base (6dfa01e) to head (fb61a6b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3226   +/-   ##
=======================================
  Coverage   51.40%   51.40%           
=======================================
  Files         288      288           
  Lines       26108    26108           
=======================================
  Hits        13421    13421           
  Misses      11961    11961           
  Partials      726      726           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[krancour]

I see that this is based on what @rpelczar had linked you to, but this process is frankly much too onerous and prone to human error. It doesn't satisfy this requirement that I included in #3171:

Each time we have a minor release, that release's branch becomes the branch that the main docs are served from. Older release branches move to subdomains like release-1-1.docs.kargo.io

We need to add a drop down to the header so that docs for older releases can be selected. It just needs to redirect readers to the correct subdomain.

This would introduce no new complications or process changes.

Edit: I had been under the impression that Docusaurus had built-in support for that approach, but it appears not. It's possible that a plugin exists for this. If not, I think this would be a very easy plugin to write.

[krancour]

See above.

[krancour]

Older release branches move to subdomains like release-1-1.docs.kargo.io

It's possible that a plugin exists for this. If not, I think this would be a very easy plugin to write.

I looked for one and didn't find one. It doesn't mean it's not our there somewhere.

Rolling our own is really not too bad. It could probably be as simple as:

1. Look at window.location.hostname to determine what version the user is currently viewing. If it's docs.kargo.io, they're viewing current docs. If it is a release docs subdomain, parse it to learn the major and minor revision numbers. This gives you everything you need to make something like a very slim banner at the top of the page that says something like "You're viewing documentation for v1.1.x". For any other value of window.location.hostname, version number is "unknown".

2. You can position a dropdown for "Other Versions" to the right of it. To find the version numbers, you can hit https://api.github.com/repos/akuity/kargo/branches to get the names of all branches. Use a regex to identify all GA release branches and cache it for some short period of time in the browser's local storage. Use that to populate the dropdown.

After this is working to our satisfaction in main, we'd backport it to release-1.1 and release-1.0.

[fykaa]

I see that this is based on what @rpelczar had linked you to, but this process is frankly much too onerous and prone to human error. It doesn't satisfy this requirement that I included in #3171
This would introduce no new complications or process changes.

I do not have access to Netlify, which made it tough for me to understand how the separate release doc is being built and deployed to their respective subdomains. I’ve noticed that this pattern of subdomain-based doc only works for some versions, which reinforces the inconsistencies in the deployment process. like, while https://release-1-1.docs.kargo.io works, https://release-1-0.docs.kargo.io does not. seems not every version has been built and deployed to its subdomain, and I may need access to Netlify to run the build process for each missing versions. Hence, i opted to work directly with Rafal’s suggestion, it simplifies the process by treating each release as a separate static site with its subdomain.

I will start working on the custom plugin that could detect the current doc version, fetch available versions from github and provide a dropdown (with doc redirection) for users to switch between versions

[krancour]

@fykaa don't get caught up in building or deploying docs.

Please just assume that for every branch release-x-y with x > 1, the subdomain will exist. If one of them does not, I can fix it.

The reason that the 1.0 docs don't currently exist has to do with the migration we did from docs.kargo.akuity.io to docs.kargo.io. iirc, there were some changes related to the domain change that didn't get backported that far, so I just didn't deploy them. I'll investigate and fix it.

[krancour]

iirc, there were some changes related to the domain change that didn't get backported that far, so I just didn't deploy them

It was dumber than that. Something just got stuck on their end during the migration.

Should be all set now.

All of the following exist:

• docs.kargo.io (currently published from release-1.1)
• release-1-1.docs.kargo.io (published from release-1.1)
• release-1-0.docs.kargo.io (published from release-1.0)
• main.docs.kargo.io ("edge" docs, published from main)