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	9cad25a
🔍 Latest deploy log	https://app.netlify.com/sites/docs-kargo-io/deploys/6786caa63847a800083cc3f7
😎 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 52.05%. Comparing base (32291db) to head (9cad25a).
Report is 10 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3226   +/-   ##
=======================================
  Coverage   52.05%   52.05%           
=======================================
  Files         295      295           
  Lines       26695    26695           
=======================================
  Hits        13895    13895           
  Misses      12041    12041           
  Partials      759      759           

☔ 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)

[krancour]

Shouldn't you look in local storage instead of unconditionally making this request?

[fykaa]

That's a valid point, and I did consider using local storage caching. but in this case I opted not to because the fetchVersions function is only called once when the dropdown component is initially rendered. since we’re only making a single API call to fetch the data, which is then reused on subsequent renders, I felt caching might not be strictly necessary. the network tab also shows that the API call isn't repeated.

But I’m open to revisiting this if it turns out we need to optimize further by caching the branches for, say 30 minute?. Currently, API calls are only made when the page is Refreshed.

[akuitybot]

Successfully created backport PR for release-1.0:

• chore(backport release-1.0): feat: versioned docs dropdown #3278

[akuitybot]

Successfully created backport PR for release-1.1:

• chore(backport release-1.1): feat: versioned docs dropdown #3279

[akuitybot]

Successfully created backport PR for release-1.2:

• chore(backport release-1.2): feat: versioned docs dropdown #3280