Introducing attribute 'section' to support different naming upstream/downstream (#19547)

Closes #19546

docs/guides/.asciidoctorconfig

@@ -2,3 +2,5 @@
 // see: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html
 :imagesdir: {asciidoctorconfigdir}/images
 :icons: font
+:section: guide
+:sections: guides

docs/guides/getting-started/index.adoc

@@ -1,10 +1,9 @@
+= Keycloak getting started guide
 <#list ctx.guides as guide>
 :links_getting-started_${guide.id}_name: ${guide.title}
 :links_getting-started_${guide.id}_url: #${guide.id}
 </#list>
 
-= Keycloak getting started guide
-
 <#list ctx.guides as guide>
 include::${guide.template}[leveloffset=+1]
 </#list>

docs/guides/migration/index.adoc

@@ -1,10 +1,9 @@
+= Keycloak migration guide
 <#list ctx.guides as guide>
 :links_migration_${guide.id}_name: ${guide.title}
 :links_migration_${guide.id}_url: #${guide.id}
 </#list>
 
-= Keycloak migration guide
-
 <#list ctx.guides as guide>
 include::${guide.template}[leveloffset=+1]
 </#list>

docs/guides/migration/migrating-to-quarkus.adoc

@@ -57,7 +57,7 @@ Once the first user with administrative rights exists, use the command line tool
 
 By default, the new Quarkus distribution removes `/auth` from the context-path. To re-introduce the `/auth` use the https://www.keycloak.org/server/all-config?q=http-relative-path&f=build[`http-relative-path`] build option. For example:
 
-[code,bash]
+[source,bash]
 ----
 bin/kc.[sh|bat] start-dev --http-relative-path /auth
 ----

docs/guides/operator/index.adoc

@@ -1,10 +1,9 @@
+= Keycloak Operator guide
 <#list ctx.guides as guide>
 :links_server_${guide.id}_name: ${guide.title}
 :links_server_${guide.id}_url: #${guide.id}
 </#list>
 
-= Keycloak Operator guide
-
 <#list ctx.guides as guide>
 include::${guide.template}[leveloffset=+1]
 </#list>

docs/guides/pom.xml

@@ -96,6 +96,9 @@
                         <idseparator>-</idseparator>
                         <docinfo1>true</docinfo1>
                         <imagesdir>../images</imagesdir>
+                        <section>guide</section>
+                        <sections>guides</sections>
+                        <attribute-missing>warn</attribute-missing>
                     </attributes>
                 </configuration>
                 <executions>

docs/guides/server/all-config.adoc

@@ -8,6 +8,7 @@ summary="Complete list of all build options and configuration for Keycloak">
 <#list ctx.options.categories as category>
 <#assign categoryOptions=ctx.options.getValues(category)>
 <#if categoryOptions?has_content>
+[#category-${category.name()?lower_case}]
 == ${category.heading}
 
 <@opts.list options=categoryOptions></@opts.list>

docs/guides/server/caching.adoc

@@ -14,7 +14,7 @@ The current distributed cache implementation is built on top of https://infinisp
 == Enable distributed caching
 When you start Keycloak in production mode, by using the `start` command, caching is enabled and all Keycloak nodes in your network are discovered.
 
-By default, caches are using a `UDP` transport stack so that nodes are discovered using IP multicast transport based on UDP. For most production environments, there are better discovery alternatives to UDP available. Keycloak allows you to either choose from a set of pre-defined default transport stacks, or to define your own custom stack, as you will see later in this guide.
+By default, caches are using a `UDP` transport stack so that nodes are discovered using IP multicast transport based on UDP. For most production environments, there are better discovery alternatives to UDP available. Keycloak allows you to either choose from a set of pre-defined default transport stacks, or to define your own custom stack, as you will see later in this {section}.
 
 To explicitly enable distributed infinispan caching, enter this command:
 

docs/guides/server/configuration-metrics.adoc

@@ -8,7 +8,7 @@ title="Enabling Keycloak Metrics"
 summary="Learn how to enable and expose metrics from the server"
 includedOptions="metrics-enabled">
 
-Keycloak has built in support for metrics. This guide describes how to enable and configure server metrics.
+Keycloak has built in support for metrics. This {section} describes how to enable and configure server metrics.
 
 == Enabling Metrics
 

docs/guides/server/configuration-provider.adoc

@@ -7,7 +7,7 @@ title="Configuring providers"
 summary="Understand how to configure providers">
 
 The server is built with extensibility in mind and for that it provides a number of Service Provider Interfaces or SPIs, each one
-responsible for providing a specific capability to the server. In this guide, you are going to understand the core concepts around
+responsible for providing a specific capability to the server. In this {section}, you are going to understand the core concepts around
 the configuration of SPIs and their respective providers.
 
 After reading this guide, you should be able to use the concepts and the steps herein explained to install, uninstall, enable, disable, and configure

docs/guides/server/containers.adoc

@@ -8,7 +8,7 @@ title="Running Keycloak in a container"
 summary="Learn how to run Keycloak from a container image"
 includedOptions="db db-url db-username db-password features hostname https-key-store-file https-key-store-password health-enabled metrics-enabled">
 
-Keycloak handles containerized environments such as Kubernetes or OpenShift as first-class citizens. This guide describes how to optimize and run the Keycloak container image to provide the best experience running a Keycloak container.
+Keycloak handles containerized environments such as Kubernetes or OpenShift as first-class citizens. This {section} describes how to optimize and run the Keycloak container image to provide the best experience running a Keycloak container.
 
 == Creating a customized and optimized container image
 The default Keycloak container image ships ready to be configured and optimized.

docs/guides/server/db.adoc

@@ -8,7 +8,7 @@
     summary="An overview about how to configure relational databases"
     includedOptions="db db-* transaction-xa-enabled">
 
-This guide explains how to configure the Keycloak server to store data in a relational database.
+This {section} explains how to configure the Keycloak server to store data in a relational database.
 
 == Supported databases
 

docs/guides/server/enabletls.adoc

@@ -9,7 +9,7 @@ includedOptions="https-* http-enabled">
 
 Transport Layer Security (short: TLS) is crucial to exchange data over a secured channel.
 For production environments, you should never expose Keycloak endpoints through HTTP, as sensitive data is at the core of what Keycloak exchanges with other applications.
-In this guide, you will learn how to configure Keycloak to use HTTPS/TLS.
+In this {section}, you will learn how to configure Keycloak to use HTTPS/TLS.
 
 == Configuring TLS in Keycloak
 Keycloak can be configured to load the required certificate infrastructure using files in PEM format or from a Java Keystore.
@@ -60,8 +60,8 @@ You can configure the location of this truststore by running the following comma
 
 <@kc.start parameters="--https-trust-store-file=/path/to/file"/>
 
-Note that this trust store is targeted for authenticating clients where Keycloak is acting as a server. For configuring a trust store
-where Keycloak is acting as a client to external services through TLS, please consider looking at the <@links.server id="keycloak-truststore"/> guide.
+NOTE: This trust store is targeted for authenticating clients where Keycloak is acting as a server. For configuring a trust store
+where Keycloak is acting as a client to external services through TLS, see <@links.server id="keycloak-truststore"/>.
 
 === Setting the truststore password
 You can set a secure password for your truststore using the `https-trust-store-password` option:
@@ -70,7 +70,7 @@ If no password is set, the default password `password` is used.
 
 == Securing credentials
 Avoid setting a password in plaintext by using the CLI or adding it to `conf/keycloak.conf` file.
-Instead use good practices such as using a vault / mounted secret. For more detail, see the Vault Guide / Production deployment guide.
+Instead use good practices such as using a vault / mounted secret. For more detail, see <@links.server id="vault"/> and <@links.server id="configuration-production" />.
 
 == Enabling mutual TLS
 Authentication using mTLS is disabled by default. To enable mTLS certificate handling when Keycloak is the server and needs to validate certificates from requests made to Keycloaks endpoints, put the appropriate certificates in Keycloaks truststore and use the following command to enable mTLS:

docs/guides/server/health.adoc

@@ -8,7 +8,7 @@ title="Enabling Keycloak Health checks"
 summary="Learn how to enable and use Keycloak health checks"
 includedOptions="health-enabled">
 
-Keycloak has built in support for health checks. This guide describes how to enable and use the Keycloak health checks.
+Keycloak has built in support for health checks. This {section} describes how to enable and use the Keycloak health checks.
 
 == Keycloak Health checks
 
@@ -59,7 +59,7 @@ Define a https://kubernetes.io/docs/tasks/configure-pod-container/configure-live
 
 === HEALTHCHECK
 
-The Dockerfile image `+HEALTHCHECK+` instruction defines a command that will be periodically executed inside the container as it runs. The Keycloak container does not have any CLI HTTP clients installed. Consider installing `+curl+` as an additional RPM, as detailed by the containers guide. Note that your container may be less secure because of this.
+The Dockerfile image `+HEALTHCHECK+` instruction defines a command that will be periodically executed inside the container as it runs. The Keycloak container does not have any CLI HTTP clients installed. Consider installing `+curl+` as an additional RPM, as detailed by the <@links.server id="containers" /> {section}. Note that your container may be less secure because of this.
 
 == Available Checks
 

docs/guides/server/index.adoc

@@ -1,10 +1,9 @@
+= Keycloak server guide
 <#list ctx.guides as guide>
 :links_server_${guide.id}_name: ${guide.title}
 :links_server_${guide.id}_url: #${guide.id}
 </#list>
 
-= Keycloak server guide
-
 <#list ctx.guides as guide>
 include::${guide.template}[leveloffset=+1]
 </#list>

docs/guides/server/logging.adoc

@@ -15,7 +15,7 @@ Keycloak uses the JBoss Logging framework. The following is a high-level overvie
 ** GELF
 
 == Logging configuration
-Logging is done on a per-category basis in Keycloak. You can configure logging for the root log level or for more specific categories such as `org.hibernate` or `org.keycloak`. This guide describes how to configure logging.
+Logging is done on a per-category basis in Keycloak. You can configure logging for the root log level or for more specific categories such as `org.hibernate` or `org.keycloak`. This {section} describes how to configure logging.
 
 === Log levels
 
@@ -97,7 +97,7 @@ The format string supports the symbols in the following table:
 |%r|Relative time|Render the time in milliseconds since the start of the application log.
 |%s|Simple message|Renders only the log message without exception trace.
 |%t|Thread name|Renders the thread name.
-|%t{id}|Thread ID|Render the thread ID.
+|%t++{id}++|Thread ID|Render the thread ID.
 |%z{<zone name>}|Timezone|Set the time zone of log output to <zone name>.
 |%L|Line number|Render the line number of the log message.
 |====

docs/guides/templates/guide.adoc

@@ -15,6 +15,6 @@
 <#if includedOptions?has_content>
 == Relevant options
 
-<@opts.list options=ctx.options.getOptions(includedOptions)></@opts.list>
+<@opts.list options=ctx.options.getOptions(includedOptions) anchor=false></@opts.list>
 </#if>
 </#macro>

docs/guides/templates/options.adoc

@@ -4,7 +4,7 @@
 </#list>
 </#macro>
 
-<#macro list options buildIcon=true>
+<#macro list options buildIcon=true anchor=true>
 [cols="12a,4",role="options"]
 |===
 | |Value
@@ -15,7 +15,7 @@
 
 [.options-description]#${option.description}#
 
-[#option-extended-${option.key},role="options-extended"]
+[<#if anchor>#option-extended-${option.key},</#if>role="options-extended"]
 --
 <#if option.descriptionExtended?has_content>[.options-description-extended]#${option.descriptionExtended!}#</#if>