fix: add the version to the guide heading

[shawkins]

closes: keycloak/keycloak#33532

This is a compromise between being subtle and verbose.

Alternatives include:

• an even more sublte option of just adding the version to the root of the breadcrumbs
• a more verbose option of using an alternative banner to the nightly warning, that explains the guide is only for the lastest and greated released version and may not be valid for older releases.

[ahus1]

Thank you for this PR. I see that this now adds the version very prominently to head headline.

I assume people are commonly used to a drop down for versions, similar to https://getbootstrap.com/docs/5.1/getting-started/introduction/

May I ask you to change it to a selector for nightly and the current release? This would also open the door that we would eventually add a link to a previous minor release as well.

[shawkins]

Added a dropdown in the top nav on the guides page. And a dropdown on each guide page. This should provide the missing context referenced in https://github.com/keycloak/keycloak/issues/33532

We are not using dropdowns for: Docs, Downloads, and versioned guides like the Server Developer's guide.

Tried to update the guide entry links to be guide specific, but in some cases I believe this may provide links that don't work (similar to how hibernate's latest links don't work, see What's New on https://hibernate.org/orm/documentation/7.2/). I'm not sure about the handling of an external guide.

[shawkins]

Any objections @vmuzikar?

[vmuzikar]

A dropdown for switching between latest and nightly is a good idea, though I think we can make the UI a bit smoother. I'll try to come up with something early next week.

[vmuzikar]

I attempted to enhance the UI a little bit, created https://github.com/shawkins/keycloak-web/pull/1. Let me know what you think.

Before

---

---

After

---

[shawkins]

I attempted to enhance the UI a little bit, created https://github.com/shawkins/keycloak-web/pull/1. Let me know what you think.

Styling the nav bar dropdown seems good.

I'm not sure about putting the other version in front of the breadcrumb. It may not be clear whether that should link to the current doc in another version or simply take you to the doc root for another version.

I'd be more in favor of:

• putting the version dropdown at the end of the bread crumbs.

• Or following one of our existing locations:

  • The placement of the version after the title in this pr was to be consistent with https://www.keycloak.org/documentation and https://www.keycloak.org/downloads
  • We are also doing a standalone version at the top of the doc https://www.keycloak.org/docs/latest/server_development/index.html

[vmuzikar]

I'm not sure about putting the other version in front of the breadcrumb. It may not be clear whether that should link to the current doc in another version or simply take you to the doc root for another version.

My thinking was that it stays on a same place – top left corner – as in the guides list.

• putting the version dropdown at the end of the bread crumbs

That would mean the selector would not have a stable place – it'd be moving based on the size of the breadcrumbs. Or perhaps we could align it right so it would be next to the nav list on the right, WDYT?

• The placement of the version after the title in this pr was to be consistent with

That doesn't IMHO looks a bit off if it needs to be an interactive element - the select.

[shawkins]

That would mean the selector would not have a stable place – it'd be moving based on the size of the breadcrumbs. Or perhaps we could align it right so it would be next to the nav list on the right, WDYT?

Doing right alignment would look like https://hibernate.org/orm/documentation/7.2/ - that seems fine.

[shawkins]

@vmuzikar I'm not sure if you have time for updating the pr, so I'll do your proposed changes.