Fix references using a title instead of an id

docs/src/main/asciidoc/doc-reference.adoc

@@ -42,6 +42,7 @@ Content from this repository is published to the https://quarkus.io/guides/[Quar
 - Documentation built from the main branch is published nightly (main-SNAPSHOT).
 - Documentation for other branches is published at release time.
 
+[[titles-headings]]
 == Titles and headings
 
 Regardless of content type, ensure that the main title and any headings in your document are:
@@ -131,6 +132,7 @@ Suffix:: The file name should reflect the document type:
 
 == Document structure
 
+[[document-header]]
 === Document header
 
 Each document should define a header for document-scoped attributes. 
@@ -145,9 +147,9 @@ Minimally, each document should define and id and a title, and include common at
 ----
 
 <1> Use the filename as the ID for the document.
-<2> Define the document title following guidance in <<Titles and headings>>.
+<2> Define the document title following guidance in <<titles-headings>>.
 <3> Include common document attributes.
-<4> Specify the relevant <<Categories>> (comma separated).
+<4> Specify the relevant <<categories>> (comma separated).
 
 [[doc-header-optional]]
 ==== Other common document header attributes
@@ -319,6 +321,7 @@ examples:
 
 == Document attributes and variables
 
+[[categories]]
 === Categories
 
 Quarkus documentation is grouped into the following categories. 
@@ -350,7 +353,7 @@ Quarkus documentation is grouped into the following categories.
 | writing-extensions | Writing Extensions
 |===
 
-Tag your content to improve findability by adding at least one category to the categories attribute line in the <<Document header,document header>>. To add multiple categories, use comma-separated values. For example:
+Tag your content to improve findability by adding at least one category to the categories attribute line in the <<document-header,document header>>. To add multiple categories, use comma-separated values. For example:
 
 [source,asciidoc]
 ----

docs/src/main/asciidoc/grpc-getting-started.adoc

@@ -84,7 +84,8 @@ You can also download the suitable binary and specify the location via
 `-Dquarkus.grpc.protoc-path=/path/to/protoc`.
 
 
-Alternatively to using the `generate-code` goal of the `quarkus-maven-plugin`, you can use `protobuf-maven-plugin` to generate these files, more in <<Generating Java files from proto with protobuf-maven-plugin>>
+Alternatively to using the `generate-code` goal of the `quarkus-maven-plugin`, you can use `protobuf-maven-plugin` to generate these files.
+See the <<protobuf-maven-plugin>> section for more information.
 
 Let's start with a simple _Hello_ service.
 Create the `src/main/proto/helloworld.proto` file with the following content:
@@ -355,6 +356,7 @@ Then, open http://localhost:8080/hello/quarkus in a browser, and you should get
 Like any other Quarkus applications, you can package it with: `mvn package`.
 You can also package the application into a native executable with: `mvn package -Pnative`.
 
+[[protobuf-maven-plugin]]
 == Generating Java files from proto with protobuf-maven-plugin
 
 Alternatively to using Quarkus code generation to generate stubs for `proto` files, you can also use

docs/src/main/asciidoc/kafka.adoc

@@ -350,7 +350,7 @@ When the processing continues from a previously persisted offset, it seeks the K
 The checkpoint strategy holds locally the processing state associated with the latest offset, and persists it periodically to the state store (period specified by `auto.commit.interval.ms` (default: 5000)). 
 The connector will be marked as unhealthy if no processing state is persisted to the state store in `checkpoint.unsynced-state-max-age.ms` (default: 10000). 
 If `checkpoint.unsynced-state-max-age.ms` is set to less than or equal to 0, it does not perform any health check verification. 
-For more information, see <<Stateful processing with Checkpointing>>
+For more information, see <<stateful-processing-checkpointing>>
 
 - `latest` commits the record offset received by the Kafka consumer as soon as the associated message is acknowledged (if the offset is higher than the previously committed offset).
 This strategy provides at-least-once delivery if the channel processes the message without performing any asynchronous processing.
@@ -698,6 +698,7 @@ Quarkus autodetects batch types for incoming channels and sets batch configurati
 You can configure batch mode explicitly with `mp.messaging.incoming.$channel.batch` property.
 ====
 
+[[stateful-processing-checkpointing]]
 === Stateful processing with Checkpointing
 
 [IMPORTANT]

docs/src/main/asciidoc/reactive-sql-clients.adoc

@@ -290,7 +290,7 @@ client.preparedQuery("SELECT id, name FROM fruits WHERE id = $1").execute(Tuple.
 ----
 
 TIP: For PostgreSQL, the SQL string can refer to parameters by position, using `$1`, `$2`, ...etc.
-Please refer to the <<Database Clients details>> section for other databases.
+Please refer to the <<reactive-sql-clients-details>> section for other databases.
 
 Similar to the simple `query` method, `preparedQuery` returns an instance of `PreparedQuery<RowSet<Row>>`.
 Equipped with this tooling, we are able to safely use an `id` provided by the user to get the details of a particular fruit:

docs/src/main/asciidoc/security-authentication-mechanisms-concept.adoc

@@ -15,8 +15,8 @@ Before you choose an authentication mechanism for securing your Quarkus applicat
 
 Some supported authentication mechanisms are built into Quarkus, and some require you to add an extension, all of which are detailed in the following sections on this page:
 
-* <<Built-in authentication mechanisms>>
-* <<Other supported authentication mechanisms>>
+* <<built-in-authentication-mechanisms>>
+* <<other-supported-authentication-mechanisms>>
 
 The following table maps specific authentication requirements to a supported mechanism that you can use in Quarkus:
 
@@ -40,6 +40,7 @@ The following table maps specific authentication requirements to a supported mec
 
 See also the <<table>> table featured later in this section.
 
+[[built-in-authentication-mechanisms]]
 == Built-in authentication mechanisms
 
 Quarkus Security provides the following built-in authentication support:
@@ -152,22 +153,24 @@ X509Certificate certificate = credential.getCertificate();
 The information from the client certificate can be used to enhance Quarkus `SecurityIdentity`. For example, you can add new roles after checking a client certificate subject name, and so on.
 For more information about customizing Quarkus `SecurityIdentity`, see xref:security-customization.adoc#security-identity-customization[SecurityIdentity customization] in the "Security customization" topic.
 
+[[other-supported-authentication-mechanisms]]
 == Other supported authentication mechanisms
 
 Quarkus Security also supports the following authentication mechanisms through extensions:
 
-* <<WebAuthn authentication>>
-* <<OpenID Connect authentication>>
-* <<SmallRye JWT authentication>>
-* <<OAuth2 authentication>>
+* <<webauthn-authentication>>
+* <<openid-connect-authentication>>
+* <<smallrye-jwt-authentication>>
+* <<oauth2-authentication>>
 
+[[webauthn-authentication]]
 === WebAuthn authentication
 
 https://webauthn.guide/[WebAuthn] is an authentication mechanism that replaces passwords.
 When you write a service for registering new users, or logging them in, instead of asking for a password, you can use WebAuthn, which replaces the password.
 For more information, see xref:security-webauthn-concept.adoc[Secure a Quarkus application by using the WebAuthn authentication mechanism].
 
-
+[[openid-connect-authentication]]
 === OpenID Connect authentication
 
 OpenID Connect (OIDC) is an identity layer that works on top of the OAuth 2.0 protocol. OIDC enables client applications to verify the identity of a user based on the authentication performed by the OIDC provider and to retrieve basic information about that user.
@@ -182,7 +185,7 @@ However, opaque (binary) tokens can only be introspected remotely.
 
 [NOTE]
 ====
-Using the Quarkus OIDC extension, both Bearer Token and Authorization Code Flow mechanisms use <<smallrye-jwt, SmallRye JWT>> to represent JWT tokens as MicroProfile JWT `org.eclipse.microprofile.jwt.JsonWebToken`.
+Using the Quarkus OIDC extension, both Bearer Token and Authorization Code Flow mechanisms use <<smallrye-jwt-authentication, SmallRye JWT>> to represent JWT tokens as MicroProfile JWT `org.eclipse.microprofile.jwt.JsonWebToken`.
 ====
 
 ==== Additional Quarkus resources for OIDC authentication
@@ -229,7 +232,7 @@ This filter can be used to propagate the access token to the downstream services
 
 For more information, see the xref:security-openid-connect-client.adoc[OpenID Connect client and token propagation quickstart] and xref:security-openid-connect-client-reference.adoc[OpenID Connect (OIDC) and OAuth2 client and filters reference] guides.
 
-[[smallrye-jwt]]
+[[smallrye-jwt-authentication]]
 === SmallRye JWT authentication
 
 The `quarkus-smallrye-jwt` extension provides a MicroProfile JSON Web Token (JWT) 1.2.1 implementation and multiple options to verify signed and encrypted `JWT` tokens and represents them as `org.eclipse.microprofile.jwt.JsonWebToken`.
@@ -239,6 +242,7 @@ The `quarkus-smallrye-jwt` extension provides a MicroProfile JSON Web Token (JWT
 
 For more information, see xref:security-jwt.adoc[Using SmallRye JWT role-based access control].
 
+[[oauth2-authentication]]
 === OAuth2 authentication
 
 `quarkus-elytron-security-oauth2` provides an alternative to the `quarkus-oidc` Bearer Token authentication mechanism. `quarkus-elytron-security-oauth2` is based on `Elytron` and is primarily intended for introspecting opaque tokens remotely.

docs/src/main/asciidoc/security-jwt.adoc

@@ -288,10 +288,11 @@ mp.jwt.verify.issuer=https://example.com/issuer #<2>
 
 quarkus.native.resources.includes=publicKey.pem #<3>
 ----
-<1> We are setting public key location to point to a classpath publicKey.pem location. We will add this key in part B, <<Adding a Public Key>>.
+<1> We are setting public key location to point to a classpath publicKey.pem location. We will add this key in part B, <<add-public-key>>.
 <2> We are setting the issuer to the URL string `https://example.com/issuer`.
 <3> We are including the public key as a resource in the native executable.
 
+[[add-public-key]]
 === Adding a Public Key
 
 The https://tools.ietf.org/html/rfc7519[JWT specification] defines various levels of security of JWTs that one can use.
@@ -642,6 +643,7 @@ Note you can also use the injected `JsonWebToken` to access the individual claim
 
 Please see link:https://download.eclipse.org/microprofile/microprofile-jwt-auth-1.2/microprofile-jwt-auth-spec-1.2.html#_cdi_injection_requirements[MP JWT CDI Injection Requirements] for more details.
 
+[[supported-public-key-formats]]
 === Supported Public Key Formats
 
 Public Keys may be formatted in any of the following formats, specified in order of
@@ -1016,7 +1018,7 @@ include::{generated-dir}/config/quarkus-smallrye-jwt.adoc[opts=optional, levelof
 [cols="<m,<m,<2",options="header"]
 |===
 |Property Name|Default|Description
-|mp.jwt.verify.publickey|none|The `mp.jwt.verify.publickey` config property allows the Public Key text itself to be supplied as a string.  The Public Key will be parsed from the supplied string in the order defined in the <<Supported Public Key Formats>> section.
+|mp.jwt.verify.publickey|none|The `mp.jwt.verify.publickey` config property allows the Public Key text itself to be supplied as a string.  The Public Key will be parsed from the supplied string in the order defined in the <<supported-public-key-formats>> section.
 |mp.jwt.verify.publickey.location|none|Config property allows for an external or internal location of Public Key to be specified.  The value may be a relative path or a URL. If the value points to an HTTPS based JWK set then, for it to work in native mode, the `quarkus.ssl.native` property must also be set to `true`, see xref:native-and-ssl.adoc[Using SSL With Native Executables] for more details.
 |mp.jwt.verify.publickey.algorithm|`RS256`|Signature algorithm. Set it to `ES256` to support the Elliptic Curve signature algorithm.
 |mp.jwt.decrypt.key.location|none|Config property allows for an external or internal location of Private Decryption Key to be specified.

docs/src/main/asciidoc/security-overview-concept.adoc

@@ -21,12 +21,12 @@ Quarkus Security also supports the following features:
 
 * xref:security-proactive-authentication-concept.adoc[Proactive authentication]
 * xref:http-reference.adoc#ssl[Secure connections with SSL/TLS]
-* <<Cross-origin resource sharing>>
-* <<Cross-site Request Forgery (CSRF) prevention>>
-* <<SameSite cookies>>
-* <<Secrets engines>>
-* <<Secure serialization>>
-* <<Secure auto-generated resources by REST Data with Panache>>
+* <<cross-origin-resource-sharing>>
+* <<csrf-prevention>>
+* <<samesite-cookies>>
+* <<secrets-engines>>
+* <<secure-serialization>>
+* <<rest-data-panache>>
 * xref:security-vulnerability-detection-concept.adoc[Security vulnerability detection and National Vulnerability Database (NVD) registration]
 
 Quarkus Security is also highly customizable. For more information, see xref:security-customization.adoc[Security customization].
@@ -46,32 +46,38 @@ Guidance for testing Quarkus Security features and ensuring that your Quarkus ap
 
 == More about security features in Quarkus
 
+[[cross-origin-resource-sharing]]
 === Cross-origin resource sharing
 
 To make your Quarkus application accessible to another application running on a different domain, you need to configure cross-origin resource sharing (CORS).
 For more information about the CORS filter that is provided by Quarkus, see the xref:http-reference.adoc#cors-filter[HTTP reference] information.
 
+[[csrf-prevention]]
 === Cross-site Request Forgery (CSRF) prevention
 
 Quarkus Security provides a RESTEasy Reactive filter that can protect your applications against a https://owasp.org/www-community/attacks/csrf[Cross-Site Request Forgery] attack.
 For more information, see xref:security-csrf-prevention.adoc[Cross-Site Request Forgery Prevention].
 
+[[samesite-cookies]]
 === SameSite cookies
 
 You can add a https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite[SameSite] cookie property to any of the cookies set by a Quarkus endpoint.
 For more information, see xref:http-reference.adoc#same-site-cookie[SameSite cookies].
 
+[[secrets-engines]]
 === Secrets engines
 Secrets engines are components that store, generate, or encrypt data.
 
 Quarkus provides comprehensive HashiCorp Vault support.
 For more information, see the link:{vault-guide}[Quarkus and HashiCorp Vault] documentation.
 
+[[secure-serialization]]
 === Secure serialization
 
 If your Quarkus Security architecture includes RESTEasy Reactive and Jackson, Quarkus can limit the fields that are included in JSON serialization based on the configured security.
 For more information, see xref:resteasy-reactive.adoc#secure-serialization[Writing REST services with RESTEasy Reactive].
 
+[[rest-data-panache]]
 === Secure auto-generated resources by REST Data with Panache
 
 If you're using the REST Data with Panache extension to auto-generate your resources, you can still use the Security annotations within the package `jakarta.annotation.security`.