feat(docs): introduce versioned documentation for v5.x releases by aerben · Pull Request #3308 · operator-framework/java-operator-sdk

aerben · 2026-04-22T13:34:03Z

Implements Docsy's versioning feature so each v5.x minor release has its own archived snapshot at javaoperatorsdk.io/v5.X/, with a version dropdown in the navbar and an archived-version banner for old releases.

Changes:

docs/hugo.toml: add [[params.versions]] entries for latest/v5.0-v5.3, update version param from placeholder "0.0" to "latest"
docs/content: replace all 12 absolute https://javaoperatorsdk.io/... links with content-relative paths so they resolve correctly under any baseURL (fixes links in reconciler.md, workflows.md, dependent-resources.md, faq/_index.md, v3-1-migration.md, v4-4-migration.md, v4-5-migration.md)
.github/workflows/hugo.yaml: extend the build job to extract each v5.x tagged release via git-archive, patch its hugo.toml for archived mode, build with a versioned baseURL, and place the output in a subdirectory of the main public/ artifact before deploying to GitHub Pages

Closes #2905

Copilot

Pull request overview

This PR adds Docsy documentation versioning so the site can publish “latest” docs alongside archived snapshots for each v5.x minor release (e.g., /v5.3/), including a navbar version selector and archived-version banner behavior.

Changes:

Adds Docsy version selector entries to docs/hugo.toml and updates the docs “version” label to latest.
Rewrites documentation links from absolute https://javaoperatorsdk.io/... to content-relative paths so they resolve under any versioned baseURL.
Extends the GitHub Pages workflow to build and publish multiple tagged v5.x doc snapshots into versioned subdirectories.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`docs/hugo.toml`	Defines `latest` and v5.0–v5.3 entries for Docsy’s version selector and updates the displayed version label.
`docs/content/en/docs/migration/v4-5-migration.md`	Converts an internal link to a content-relative path for versioned builds.
`docs/content/en/docs/migration/v4-4-migration.md`	Converts an internal link to a content-relative path for versioned builds.
`docs/content/en/docs/migration/v3-1-migration.md`	Converts an internal link to a content-relative path for versioned builds.
`docs/content/en/docs/faq/_index.md`	Converts a release-notes link to a content-relative path for versioned builds.
`docs/content/en/docs/documentation/reconciler.md`	Converts an internal docs link to a content-relative path for versioned builds.
`docs/content/en/docs/documentation/dependent-resource-and-workflows/workflows.md`	Converts internal links to content-relative paths for versioned builds.
`docs/content/en/docs/documentation/dependent-resource-and-workflows/dependent-resources.md`	Converts internal links to content-relative paths for versioned builds.
`.github/workflows/hugo.yaml`	Builds “latest” plus archived v5.x docs from tags and publishes them under versioned subdirectories on Pages.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

aerben · 2026-04-22T14:00:37Z

The actions build still has some hickups that I am fixing on a personal copy of the project.

csviri · 2026-04-22T15:56:13Z

Thank you @aerben!! will try to take a look soon

aerben · 2026-04-22T18:16:41Z

Alright, I got it working @csviri https://aerben.github.io/josdk-docs-test/

xstefank · 2026-04-23T07:17:55Z

Thanks @aerben, I think this is a great idea. I noticed in your preview that v5.2 downwards changes colors. Is that expected?

Why is this PR a draft?

aerben · 2026-04-23T07:48:04Z

@xstefank thank you for taking a look. The PR is a draft because the implementation is mostly finished, but I found some glitches on the page like e.g. a vanishing search box when switching between versions that I want to work on before making the PR ready for review.

EDIT: It's fine now and I will let Copilot have a go at the code again

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

metacosm

I'm not really knowledgeable wrt Hugo so I'll let others decide whether this is appropriate or not. The demo site seems to work well enough, though I wish changing the version wouldn't reset the page the user is currently on (that said, I understand that it's probably way easier like that).

csviri · 2026-04-23T12:07:11Z

@aerben loks awesome thank you!!

just some nitpicking: when selecting the version, would it be possible to show the actual version?

csviri · 2026-04-23T12:58:18Z

+              | grep -E '^v5\.[0-9]+\.[0-9]+$' | head -1)
+            VERSIONS+=("${latest}:${minor}")
+          done
+


Please echo here the final values.

csviri

Added just some minor nitpicks, it looks great thank you @aerben !

aerben · 2026-04-23T18:41:44Z

I will make your requested changes and go through the pages one last time to check that all links are correct

Build archived docs for v5.0–v5.3 alongside the latest docs and deploy them as subdirectories under GitHub Pages. A version selector dropdown lets readers switch between releases. Signed-off-by: Alexander Erben <alex@it-erben.com>

aerben · 2026-04-23T18:52:37Z

Alright, from my side this is ready to merge

Copilot AI review requested due to automatic review settings April 22, 2026 13:34

openshift-ci Bot requested review from metacosm and xstefank April 22, 2026 13:34

Copilot started reviewing on behalf of aerben April 22, 2026 13:34 View session

Copilot AI reviewed Apr 22, 2026

View reviewed changes

Comment thread docs/hugo.toml Outdated

Comment thread .github/workflows/hugo.yaml Outdated

Comment thread .github/workflows/hugo.yaml Outdated

aerben force-pushed the feat/versioned-docs branch from 1f918a4 to 4ec951c Compare April 22, 2026 13:47

aerben requested a review from Copilot April 22, 2026 13:48

Copilot started reviewing on behalf of aerben April 22, 2026 13:48 View session

aerben force-pushed the feat/versioned-docs branch 2 times, most recently from 6905d81 to ee3358d Compare April 22, 2026 13:52

aerben marked this pull request as draft April 22, 2026 13:52

openshift-ci Bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Apr 22, 2026

Copilot AI reviewed Apr 22, 2026

View reviewed changes

Comment thread .github/workflows/hugo.yaml Outdated

aerben force-pushed the feat/versioned-docs branch from ee3358d to 8c69b70 Compare April 22, 2026 13:58

aerben force-pushed the feat/versioned-docs branch from 8c69b70 to 671a18b Compare April 22, 2026 18:16

xstefank requested a review from csviri April 23, 2026 07:16

aerben force-pushed the feat/versioned-docs branch from 671a18b to 8e642ef Compare April 23, 2026 08:08

aerben requested a review from Copilot April 23, 2026 08:09

aerben marked this pull request as ready for review April 23, 2026 08:09

openshift-ci Bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Apr 23, 2026

Copilot started reviewing on behalf of aerben April 23, 2026 08:09 View session

Copilot AI reviewed Apr 23, 2026

View reviewed changes

Comment thread docs/content/en/docs/documentation/dependent-resource-and-workflows/workflows.md Outdated

Comment thread docs/content/en/docs/faq/_index.md Outdated

aerben force-pushed the feat/versioned-docs branch from 8e642ef to d581499 Compare April 23, 2026 08:17

aerben requested a review from Copilot April 23, 2026 08:17

Copilot started reviewing on behalf of aerben April 23, 2026 08:18 View session

Copilot AI reviewed Apr 23, 2026

View reviewed changes

Comment thread .github/workflows/hugo.yaml Outdated

Comment thread .github/workflows/hugo.yaml

Comment thread .github/workflows/hugo.yaml

aerben force-pushed the feat/versioned-docs branch from d581499 to 7f731bc Compare April 23, 2026 08:26

metacosm reviewed Apr 23, 2026

View reviewed changes

Comment thread .github/workflows/hugo.yaml Outdated

metacosm reviewed Apr 23, 2026

View reviewed changes

aerben force-pushed the feat/versioned-docs branch from 7f731bc to 92c6413 Compare April 23, 2026 12:41

csviri reviewed Apr 23, 2026

View reviewed changes

csviri approved these changes Apr 23, 2026

View reviewed changes

aerben force-pushed the feat/versioned-docs branch from 92c6413 to 605a827 Compare April 23, 2026 18:43

aerben force-pushed the feat/versioned-docs branch from 605a827 to 8db13b9 Compare April 23, 2026 18:48

Conversation

aerben commented Apr 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

aerben commented Apr 22, 2026

Uh oh!

csviri commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aerben commented Apr 22, 2026

Uh oh!

xstefank commented Apr 23, 2026

Uh oh!

aerben commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

metacosm left a comment

Choose a reason for hiding this comment

Uh oh!

csviri commented Apr 23, 2026

Uh oh!

csviri Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

aerben Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

csviri left a comment

Choose a reason for hiding this comment

Uh oh!

aerben commented Apr 23, 2026

Uh oh!

aerben commented Apr 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

csviri commented Apr 22, 2026 •

edited

Loading

aerben commented Apr 23, 2026 •

edited

Loading