Dropdown options on Documentation pointing to 21.1 endpoint instead of latest and throwing 404 when clicking on it.

[BrayanMnz]

Before reporting an issue

• I have searched existing issues
• I have reproduced the issue with the latest release

Area

docs

Describe the bug

When on the documentation page, for example: https://www.keycloak.org/docs/latest/server_development/
and hovering the mouse over the top left Server Developer dropdown, the options on the dropdown are redirecting to a path like this one https://www.keycloak.org/docs/21.1/securing_apps/

See the 21.1 on the version fragment of the uri, this should be latest I think.
if you click on it you'll see that it throws a 404

Version

latest

Expected behavior

It should redirect to the correct page instead of throwing a 404

Actual behavior

404

How to Reproduce?

When on the documentation page, for example: https://www.keycloak.org/docs/latest/server_development/
and hovering the mouse over the top left Server Developer dropdown, the options on the dropdown are redirecting to a path like this one https://www.keycloak.org/docs/21.1/securing_apps/

Anything else?

No response

[BrayanMnz]

I'm happy to submit a PR for this one,
I was looking at the source code for the root cause of this but, I haven't identified it
I think that it is related to the project_buildType variable not being set as latest.

Any guidance for solving this would be appreciated, thanks!

[BrayanMnz]

Apparently no code changes are needed here,
looks like the issue is because documentation was not built using the latest profile

keycloak/docs/documentation/pom.xml

Line 65 in 8367f8f

<id>latest</id>

[stianst]

This was a regression due to migrating the documentation repository to the main repository that changed the way we build the docs. If I remember correctly we used to build both a latest and a release version of the docs, which would have different links + also would mark the docs as latest in the top header. We'll need to figure out a new way of doing this as the new release process with the mono-repo doesn't really enable building two versions of the docs easily.

[stianst]

@ahus1 FIY

[ahus1]

@stianst - sorry that I've missed that. I see you assigned it to you ... feel free to assign it to me and I'll work on this from tomorrow?

[stianst]

@ahus1 if you could handle it that'd be great. Was probably me that missed this not you 😉

[BrayanMnz]

If you guys need any help, just add any helpful hint to this thread and I can take a look also. @ahus1 @stianst

[ahus1]

@BrayanMnz - If you want to create a pull request with the necessary changes, go ahead. I still need to figure out what needs to change here.

As an alternative I'd be happy for a reviewer once I have created one. If I don't hear from you I will start having a look on Monday the latest.

[ahus1]

@stianst - I analyzed the current behavior, and this is what I found:

• Starting from KC 19.0.0, we publish the patch releases of the docs, and not only the minor releases of the docs
• Starting from KC 20.0.0 onward, we use a symlink for "latest", which breaks the logic around the link to the "lastest" docs in the header

Do we want to keep the functionality for "latest" vs. "archive", or would we rather drop it? It seems to be broken from KC 20.0.0 onward once the symlink was used. From then on, even the old version shows latest, see for example https://www.keycloak.org/docs/20.0.5/securing_apps/index.html

If we drop it, we could have it again once we migrate to a tool like Antora. Antora will re-render all the old docs with their AsciiDoc content when publishing. If we want to keep it, it could be solved by adding some JavaScript, which I'd rather not.

So I'd like to go ahead and remove the "latest" vs. "archive" feature. In this case it would behave like in the KC20 releases where when switching the guides, it would always jump to the latest version. And the yellow vs green text will be removed.

Please confirm.

[ahus1]

There are now two PR which will fix part of the problems:

• Use the "latest" profile for the docs so that it behaves like in KC20 keycloak-rel/keycloak-rel#99
• Fix the links to the docs which have three groups of digits starting from KC19 #20035

[ahus1]

PR to remove latest vs. archive from the document header: #20103

[ahus1]

Backport created: #20110

[ahus1]

PR to fix the old docs created: keycloak/keycloak.github.io#21