Group or hide versions in version switcher

[pkosiec]

Overview

The version list is getting longer and longer. We should figure out a way to display just last 3 versions, and hide legacy/archived ones under All versions. We can see the following pages for inspiration (both are OS, so we can check the code how the "All versions" section is implemented):

• docusaurus.io
• https://jestjs.io/docs/getting-started

AC

• Display last three/five versions in the version switcher (to agree)
• Keep the previous versions, but hidden under "All/archived versions" page (see the impl in docusaurus or jest documentation)

[pkosiec]

Open questions for @brampling

• How many versions we should support officially?
• Can we remove older docs and point to GitHub for archive? some interactive parts (admonities, tabs) won't work anymore
  • Or, should we point for older Cloudflare Builds? This is what Docusaurus does. We can find such link in older commits, e.g. https://github.com/kubeshop/botkube-docs/runs/12481675291

[brampling]

Based on the version split it's pretty even with a concentration on 0.18.0 and 1.0.0.

I would keep the older ones in the archive list and not remove them and point to GitHub or Cloudflare. Let's put everything older than 1.0.0 in the archive list.

[yo-404]

Hi @pkosiec , I was working on this issue . Screenshot for the same has been uploaded below , please go through the same and let me know if any changes are required .

[yo-404]

For the older versions , we can put it in archive list and point it to cloudflare /netlify . That's what docusaurus does , whereas jest uses a subdomain for pointing to archive docs

[pkosiec]

Whoa, awesome work @yo-404! 🚀 That looks great!

Yeah, let's skip the Archived versions section from the dropdown:

Also, one question: how does it behave after releasing new docs version (running docusaurus docs:version), which we do here: https://github.com/kubeshop/botkube-docs/blob/main/.github/workflows/release.yml#L83

Can we e.g. maintain the list of the last 3-5 releases, and automatically move the previous ones to the archived ones?

[yo-404]

Initial Approach - since Docusaurus does not have a built-in feature to enforce a specific number of versions in the type: "docsVersionDropdown", . Due to this ,we will have to change the versions.json (by default created by docusaurus) file with desired number of doc versions and put the rest of the versions in versionsArchived.json . Using versionArchived.json here to store archived version labels and urls - to redirect it either locally or to snapshots like netlify/cloudflare .

---

New Approach Other solution that I came up with is that we can create a custom dropdown and on the Navbar . In this approach we can use a custom made version1.json file with label and url fields . We can use this json file to populate the fields inside the navbar and on the all-versions page . with our custom version1.json file, we can enforce data manipulations like splice/slice to show only the top 5 results. Rest values can be shown in archived version . This approach will work dynamically and move the previous ones to the archive list .

---

before releasing

after releasing new docs

while releasing the doc

• we can either add the new version manually into the json
• or we can add sed -i '2i "${version_number}":"/${version_number}" ' version1.json into the pipeline that can automate the versioning updation . This will add the current pushed version into our custom made version1.json .

I m open to suggestions /ideas .

[pkosiec]

Thank you @yo-404. The main goal for this task is to make sure the dropdown is not too long. While I know I posted screenshots from docusarus and jest sites, we'd prefer shorter dropdown with just a few versions.

I think the "Initial Approach" you went with is the best one. Could you please remove the "Archived versions" section from the dropdown? We'll still keep the archived ones accessible under "All versions".

Also, we can still automate archiving some docs versions at some point, right? For example, after docs release, we can use e.g. jq to remove last version from versions.json and move it to versionsArchived.json. Of course we'd need to somehow find a link to the archived version 🤔 Is that correct? Anyway, for now archiving the versions manually is totally OK.

Let me know when your PR will be ready to review! 🚀

[yo-404]

Yeah @pkosiec ,that is correct . I will look into automating the following issue .For now archiving is manual . Have put a PR for the same .Thanks 👍