From b9dc3c4835f845d13e938b1d97d6238299302d73 Mon Sep 17 00:00:00 2001 From: Lars Francke Date: Thu, 16 Jul 2026 09:18:06 +0200 Subject: [PATCH 1/3] feat: Link the CRD reference on the Stackable Hub The docs' own pages now link https://hub.stackable.tech/crds instead of the old CRD browser on crds.stackable.tech, using the new attributes: crd-ref: the listing {crd-ref}///{crd-ref-release}: a deep link crd-ref-release is ?release=dev on this branch and gets the release number on release branches (like crd-docs-version today). The old crd-docs attributes stay until the operator repos migrate their deep links to crd-ref (they do so in the planned operator sweep, one PR per repo). page-crd-docs is removed: nothing in the UI templates reads it. The OIDC provider deep link loses its per-property anchor: the Hub has section-level anchors only, so it points at #provider now. --- antora.yml | 8 ++++++-- modules/ROOT/pages/index.adoc | 2 +- modules/concepts/pages/authentication.adoc | 6 +++--- modules/concepts/pages/s3.adoc | 2 +- modules/reference/nav.adoc | 2 +- modules/tutorials/pages/authentication_with_openldap.adoc | 2 +- 6 files changed, 13 insertions(+), 9 deletions(-) diff --git a/antora.yml b/antora.yml index b862577d9..b1c0218ec 100644 --- a/antora.yml +++ b/antora.yml @@ -27,10 +27,14 @@ asciidoc: # Whether this version is already end of life. # If true, a banner will be displayed informing the user. end-of-life: false - # use the attributes below to link to the CRD docs + # The CRD reference on the Stackable Hub. crd-ref links the listing; + # deep links follow {crd-ref}///{crd-ref-release} + crd-ref: "https://hub.stackable.tech/crds" + crd-ref-release: "?release=dev" + # DEPRECATED: the old CRD browser attributes below are still used by the + # operator docs; they migrate to crd-ref repo by repo (operator sweep). crd-docs-base-url: "https://crds.stackable.tech" crd-docs: "{crd-docs-base-url}/{crd-docs-version}" # to make attributes accessible to the UI template, they need to # be prefixed with "page-" - page-crd-docs: "{crd-docs}" page-end-of-life: "{end-of-life}" diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index cac183bff..703159970 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -118,7 +118,7 @@ xref:operators:index.adoc[Operator overview] Read the CustomResourceDefinition (CRD) reference for all CRDs that are deployed by any Stackable operator. -{crd-docs}[CRD Reference {external-link-icon}^] +{crd-ref}{crd-ref-release}[CRD Reference {external-link-icon}^] ++++ diff --git a/modules/concepts/pages/authentication.adoc b/modules/concepts/pages/authentication.adoc index 458acf6ff..e5aba1ef3 100644 --- a/modules/concepts/pages/authentication.adoc +++ b/modules/concepts/pages/authentication.adoc @@ -38,7 +38,7 @@ In a diagram it would look like this: image::image$authentication-overview.drawio.svg[] -NOTE: Learn more in the xref:tutorials:authentication_with_openldap.adoc[OpenLDAP tutorial] and get a full overview of all the properties in the {crd-docs}/authentication.stackable.tech/authenticationclass/v1alpha1/#spec-provider-ldap[AuthenticationClass LDAP provider CRD reference{external-link-icon}^]. +NOTE: Learn more in the xref:tutorials:authentication_with_openldap.adoc[OpenLDAP tutorial] and get a full overview of all the properties in the {crd-ref}/authentication.stackable.tech/v1alpha1/authenticationclass{crd-ref-release}#provider.ldap[AuthenticationClass LDAP provider CRD reference{external-link-icon}^]. [#OIDC] === OpenID Connect @@ -59,7 +59,7 @@ include::example$authenticationclass-keycloak.yaml[] <7> Optionally enable TLS and configure verification. When present, connections to the idP will use `https://` instead of `http://`. See xref:tls-server-verification.adoc[]. <8> Trust certificates signed by commonly trusted Certificate Authorities. -NOTE: Get a full overview of all the properties in the {crd-docs}/authentication.stackable.tech/authenticationclass/v1alpha1/#spec-provider-oidc[AuthenticationClass OIDC provider CRD reference{external-link-icon}^]. +NOTE: Get a full overview of all the properties in the {crd-ref}/authentication.stackable.tech/v1alpha1/authenticationclass{crd-ref-release}#provider.oidc[AuthenticationClass OIDC provider CRD reference{external-link-icon}^]. [#tls] === TLS @@ -113,4 +113,4 @@ include::example$authenticationclass-static-secret.yaml[] == Further reading * xref:tutorials:authentication_with_openldap.adoc[] tutorial -* {crd-docs}/authentication.stackable.tech/authenticationclass/v1alpha1/[AuthenticationClass CRD reference{external-link-icon}^] +* {crd-ref}/authentication.stackable.tech/v1alpha1/authenticationclass{crd-ref-release}[AuthenticationClass CRD reference{external-link-icon}^] diff --git a/modules/concepts/pages/s3.adoc b/modules/concepts/pages/s3.adoc index 443a626a8..a990934b4 100644 --- a/modules/concepts/pages/s3.adoc +++ b/modules/concepts/pages/s3.adoc @@ -284,4 +284,4 @@ region: == What's next -Read the {crd-docs}/s3.stackable.tech/s3bucket/v1alpha1/[S3Bucket CRD reference{external-link-icon}^] and the {crd-docs}/s3.stackable.tech/s3connection/v1alpha1/[S3Connection CRD reference{external-link-icon}^]. +Read the {crd-ref}/s3.stackable.tech/v1alpha1/s3bucket{crd-ref-release}[S3Bucket CRD reference{external-link-icon}^] and the {crd-ref}/s3.stackable.tech/v1alpha1/s3connection{crd-ref-release}[S3Connection CRD reference{external-link-icon}^]. diff --git a/modules/reference/nav.adoc b/modules/reference/nav.adoc index f23327915..544dd7bed 100644 --- a/modules/reference/nav.adoc +++ b/modules/reference/nav.adoc @@ -1,4 +1,4 @@ * Reference -** {crd-docs}[CRD Reference {external-link-icon}^] +** {crd-ref}{crd-ref-release}[CRD Reference {external-link-icon}^] ** xref:glossary.adoc[] ** xref:duration.adoc[] diff --git a/modules/tutorials/pages/authentication_with_openldap.adoc b/modules/tutorials/pages/authentication_with_openldap.adoc index 60ebf0c6f..259650e1d 100644 --- a/modules/tutorials/pages/authentication_with_openldap.adoc +++ b/modules/tutorials/pages/authentication_with_openldap.adoc @@ -367,7 +367,7 @@ The LDAP connection details only need to be written down once, in the Authentica == Further Reading - xref:concepts:authentication.adoc[Authentication concepts page] -* {crd-docs}/authentication.stackable.tech/authenticationclass/v1alpha1/[AuthenticationClass CRD reference{external-link-icon}^] +* {crd-ref}/authentication.stackable.tech/v1alpha1/authenticationclass{crd-ref-release}[AuthenticationClass CRD reference{external-link-icon}^] - xref:superset:getting_started/index.adoc[Getting started with the Stackable Operator for Apache Superset] - xref:trino:getting_started/index.adoc[Getting started with the Stackable Operator for Trino] // TODO Operator docs for LDAP From 577a58852fedcc12603d8ca223e25c8db644caee Mon Sep 17 00:00:00 2001 From: Lars Francke Date: Tue, 21 Jul 2026 10:34:45 +0200 Subject: [PATCH 2/3] fix: Rewrite crd-ref-release when cutting a release branch make-release-branch.sh already rewrites version, prerelease and crd-docs-version; without this, a release branch would keep ?release=dev and its Hub CRD links would show bleeding-edge schemas. The Hub names releases by major.minor, so this uses DOCS_VERSION (e.g. 26.7), not VERSION (e.g. 26.7.1); the Hub 301s patch-level values but major.minor is canonical. --- scripts/make-release-branch.sh | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/scripts/make-release-branch.sh b/scripts/make-release-branch.sh index 49ee8ee38..9f7ccbc1d 100755 --- a/scripts/make-release-branch.sh +++ b/scripts/make-release-branch.sh @@ -120,6 +120,10 @@ sed -i "s/^prerelease:.*/prerelease: false/" "$ANTORA_YAML_FILE" # Set crd-docs-version key to the 'version' variable sed -i "s/^\(\s*\)crd-docs-version:.*/\1crd-docs-version: \"$VERSION\"/" "$ANTORA_YAML_FILE" +# Set the Hub release for the CRD reference links. The Hub names releases +# by major.minor, so this uses DOCS_VERSION, not VERSION. +sed -i "s/^\(\s*\)crd-ref-release:.*/\1crd-ref-release: \"?release=$DOCS_VERSION\"/" "$ANTORA_YAML_FILE" + # Display changes using git diff git diff "$ANTORA_YAML_FILE" From ab0c7a34566471895623ad072f7b6d704047ae94 Mon Sep 17 00:00:00 2001 From: Lars Francke Date: Tue, 21 Jul 2026 10:35:10 +0200 Subject: [PATCH 3/3] docs: Remind release cutters about crd-ref-release Same kind of reminder comment that crd-docs-version has, in case the attribute is ever edited by hand instead of via the release script. --- antora.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/antora.yml b/antora.yml index b1c0218ec..6075be923 100644 --- a/antora.yml +++ b/antora.yml @@ -30,6 +30,8 @@ asciidoc: # The CRD reference on the Stackable Hub. crd-ref links the listing; # deep links follow {crd-ref}///{crd-ref-release} crd-ref: "https://hub.stackable.tech/crds" + # Keep this in line with the 'version' key above: '?release=dev' on main, + # '?release=' on release branches (the release script sets it). crd-ref-release: "?release=dev" # DEPRECATED: the old CRD browser attributes below are still used by the # operator docs; they migrate to crd-ref repo by repo (operator sweep).