Merge pull request #31981 from gsmet/revert-doc-pr

Implement a transformer for compatibility with downstream documentation

docs/pom.xml

@@ -2967,6 +2967,24 @@
                             </environmentVariables>
                         </configuration>
                     </execution>
+                    <execution>
+                        <id>generate-doc-reference-index</id>
+                        <phase>prepare-package</phase>
+                        <goals>
+                            <goal>java</goal>
+                        </goals>
+                        <configuration>
+                            <skip>${skipDocs}</skip>
+                            <mainClass>io.quarkus.docs.generation.ReferenceIndexGenerator</mainClass>
+                            <arguments>
+                                <argument>${project.basedir}/target/asciidoc/sources</argument>
+                                <argument>${project.basedir}/target</argument>
+                            </arguments>
+                            <environmentVariables>
+                                <MAVEN_CMD_LINE_ARGS>${env.MAVEN_CMD_LINE_ARGS}</MAVEN_CMD_LINE_ARGS>
+                            </environmentVariables>
+                        </configuration>
+                    </execution>
                 </executions>
             </plugin>
             <plugin>

docs/src/main/asciidoc/amazon-lambda.adoc

@@ -58,7 +58,7 @@ Copy the build.gradle, gradle.properties and settings.gradle into the above-gene
 
 Execute: gradle wrapper to set up the gradle wrapper (recommended).
 
-For full Gradle details, see the xref:gradle[Gradle build] section below.
+For full Gradle details, see the <<gradle,Gradle build>> section below.
 ====
 
 [[choose]]
@@ -458,7 +458,7 @@ when using synchronous mode, due to issues in the GraalVM compilation (at presen
 Add `quarkus-jaxb` as a dependency in your Maven `pom.xml`, or Gradle `build.gradle` file.
 
 You must also force your AWS service client for SQS, SNS, S3 et al., to use the URL Connection client,
-which connects to AWS services over HTTPS, hence the inclusion of the SSL enabled property, as described in the xref:https[] section above.
+which connects to AWS services over HTTPS, hence the inclusion of the SSL enabled property, as described in the <<https>> section above.
 
 [source,java]
 ----

docs/src/main/asciidoc/cdi.adoc

@@ -167,14 +167,14 @@ The reason is that `@Inject Translator` is automatically transformed to `@Inject
 And since our `SuperiorTranslator` does not declare `@Default` only the original `Translator` bean is assignable.
 
 [[bean-scope]]
-== [[looks-good-what-is-the-bean-scope]] Looks good. What is the bean scope?
+== Looks good. What is the bean scope?
 
 The scope of a bean determines the lifecycle of its instances, i.e. when and where an instance should be created and destroyed.
 
 NOTE: Every bean has exactly one scope.
 
 [[bean-scope-available]]
-== [[what-scopes-can-i-actually-use-in-my-quarkus-application]] What scopes can I actually use in my Quarkus application?
+== What scopes can I actually use in my Quarkus application?
 
 You can use all the built-in scopes mentioned by the specification except for `jakarta.enterprise.context.ConversationScoped`.
 

docs/src/main/asciidoc/cli-tooling.adoc

@@ -428,7 +428,7 @@ The behavior of `quarkus ext ls` will vary depending on context.
 
 If you invoke the Quarkus CLI from outside of a project, Quarkus will list all the extensions available for the Quarkus release used by the CLI itself.
 
-You can also list extensions for a specific release of Quarkus using `-P` or `-S`, as described in xref:specifying-quarkus-version[Specifying the Quarkus version].
+You can also list extensions for a specific release of Quarkus using `-P` or `-S`, as described in <<specifying-quarkus-version,Specifying the Quarkus version>>.
 
 This mode uses the `--origins` format by default.
 

docs/src/main/asciidoc/config.adoc

@@ -9,7 +9,7 @@ include::_attributes.adoc[]
 :summary: Hardcoded values in your code is a no go (even if we all did it at some point ;-)). In this guide, we learn how to configure your application.
 
 IMPORTANT: The content of this guide and been revised and split into additional topics. Please check the
-xref:additional-information[Additional Information] section.
+<<additional-information,Additional Information>> section.
 
 
 Hardcoded values in your code are a _no-go_ (even if we all did it at some point ;-)).
@@ -48,7 +48,7 @@ It generates:
 A Quarkus application uses the https://github.com/smallrye/smallrye-config[SmallRye Config] API to provide all
 mechanisms related with configuration.
 
-By default, Quarkus reads configuration properties from xref:config-reference.adoc#configuration-sources[several sources].
+By default, Quarkus reads configuration properties from <<config-reference.adoc#configuration-sources,several sources>>.
 For the purpose of this guide, we will use an application configuration file located in `src/main/resources/application.properties`.
 
 Edit the file with the following content:

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
@@ -256,44 +258,6 @@ xref:{doc-guides}/doc-concept.adoc[Quarkus Documentation concepts] <1>
 ----
 <1> The cross-reference starts with `xref:`, uses a cross-reference source attribute(`\{doc-guides}`), and provides a readable description: `[Quarkus Documentation concepts]`.
 
-=== Anchors
-
-Quarkus documentation provides several ways a contributor can create and call anchors.
-To reach consistency and a better single-sourcing experience with Quarkus documentation, we ask contributors to use the `xref` approach for documenting and calling anchors.
-
-.Example
-* An anchor to a chapter inside the same `.adoc` file
-** Create an ID anchor:
-+
-[source,asciidoc]
---
- [[<anchor-ID>]]
---
-
-** Call the anchor
-+
-[source,asciidoc]
---
-xref:<anchor-ID>[]
---
-
-* A cross-file anchor
-** Create an ID anchor:
-+
-[source,asciidoc]
---
-[[<anchor-ID>]]
---
-
-** Call the anchor
-+
-[source,asciidoc]
---
-xref:<target-file>.adoc#<anchord-ID>[]
---
-
-NOTE: The `[]` part of your `xref` anchors sets up a desired anchor label in cases where the default label does not fit the content.
-
 === Reference source code 
 
 There are many ways to include source code and examples in documentation.
@@ -357,6 +321,7 @@ examples:
 
 == Document attributes and variables
 
+[[categories]]
 === Categories
 
 Quarkus documentation is grouped into the following categories. 
@@ -388,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/getting-started.adoc

@@ -45,7 +45,7 @@ This guide also covers the testing of the endpoint.
 
 == Solution
 
-We recommend that you follow the instructions from xref:bootstrapping-the-project[Bootstrapping project] and onwards to create the application step by step.
+We recommend that you follow the instructions from <<bootstrapping-the-project,Bootstrapping the project>> and onwards to create the application step by step.
 
 However, you can go right to the completed example.
 

docs/src/main/asciidoc/gradle-tooling.adoc

@@ -315,7 +315,7 @@ Then, attach your debugger to `localhost:5005`.
 
 == Import in your IDE
 
-Once you have a xref:project-creation[project generated], you can import it in your favorite IDE.
+Once you have a <<project-creation,project generated>>, you can import it in your favorite IDE.
 The only requirement is the ability to import a Gradle project.
 
 **Eclipse**

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/hibernate-orm.adoc

@@ -98,7 +98,7 @@ They will often map to Hibernate ORM configuration properties but could have dif
 
 Also, Quarkus will set many Hibernate ORM configuration settings automatically, and will often use more modern defaults.
 
-For a list of the items that you can set in `{config-file}`, see xref:hibernate-configuration-properties[Hibernate ORM configuration properties].
+For a list of the items that you can set in `{config-file}`, see <<hibernate-configuration-properties,Hibernate ORM configuration properties>>.
 
 An `EntityManagerFactory` will be created based on the Quarkus `datasource` configuration as long as the Hibernate ORM extension is listed among your project dependencies.
 
@@ -269,7 +269,7 @@ include::{generated-dir}/config/quarkus-hibernate-orm.adoc[opts=optional, levelo
 
 [NOTE]
 ====
-Do not mix xref:persistence-xml[`persistence.xml`] and `quarkus.hibernate-orm.*` properties in `{config-file}`.
+Do not mix <<persistence-xml,`persistence.xml`>> and `quarkus.hibernate-orm.*` properties in `{config-file}`.
 Quarkus will raise an exception.
 Make up your mind on which approach you want to use.
 
@@ -538,7 +538,7 @@ the https://jakarta.ee/specifications/persistence/3.0/jakarta-persistence-spec-3
 or the http://hibernate.org/dtd/hibernate-mapping-3.0.dtd[`hbm.xml` format (specific to Hibernate ORM, deprecated)]:
 
 * in `application.properties` through the (build-time) link:#quarkus-hibernate-orm_quarkus.hibernate-orm.mapping-files[`quarkus.hibernate-orm.mapping-files`] property.
-* in xref:persistence-xml[`persistence.xml`] through the `<mapping-file>` element.
+* in <<persistence-xml,`persistence.xml`>> through the `<mapping-file>` element.
 
 XML mapping files are parsed at build time.
 
@@ -857,16 +857,16 @@ configure your datasource as in the above examples and it will set up Hibernate
 More details about this connection pool can be found in xref:datasource.adoc[Quarkus - Datasources].
 
 Second Level Cache::
-As explained earlier in the xref:caching[Caching] section, you don't need to pick an implementation.
+As explained earlier in the <<caching,Caching section>>, you don't need to pick an implementation.
 A suitable implementation based on technologies from link:https://infinispan.org/[Infinispan] and link:https://github.com/ben-manes/caffeine[Caffeine] is included as a transitive dependency of the Hibernate ORM extension, and automatically integrated during the build.
 
 === Limitations
 
 XML mapping with duplicate files in the classpath::
-xref:xml-mapping[XML mapping] files are expected to have a unique path.
-
+<<xml-mapping,XML mapping>> files are expected to have a unique path.
++
 In practice, it's only possible to have duplicate XML mapping files in the classpath in very specific scenarios.
-For example, if two JARs include a `META-INF/orm.xml` file (with the same path but in different JARs),
+For example, if two JARs include a `META-INF/orm.xml` file (with the exact same path but in different JARs),
 then the mapping file path `META-INF/orm.xml` can only be referenced from a `persistence.xml`
 **in the same JAR as the `META-INF/orm.xml` file**.
 
@@ -988,7 +988,7 @@ public class CustomTenantResolver implements TenantResolver {
 <1> Annotate the TenantResolver implementation with the `@PersistenceUnitExtension` qualifier
 to tell Quarkus it should be used in the default persistence unit.
 +
-For xref:multiple-persistence-units[named persistence units], use `@PersistenceUnitExtension("nameOfYourPU")`.
+For <<multiple-persistence-units,named persistence units>>, use `@PersistenceUnitExtension("nameOfYourPU")`.
 <2> The bean is made `@RequestScoped` as the tenant resolution depends on the incoming request.
 
 From the implementation above, tenants are resolved from the request path so that in case no tenant could be inferred, the default tenant identifier is returned.
@@ -1152,7 +1152,7 @@ INSERT INTO known_fruits(id, name) VALUES (3, 'Blackberries');
 If you need a more dynamic configuration for the different tenants you want to support and don't want to end up with multiple entries in your configuration file,
 you can use the `io.quarkus.hibernate.orm.runtime.tenant.TenantConnectionResolver` interface to implement your own logic for retrieving a connection.
 Creating an application-scoped bean that implements this interface
-and annotating it with `@PersistenceUnitExtension` (or `@PersistenceUnitExtension("nameOfYourPU")` for a xref:multiple-persistence-units[named persistence unit])
+and annotating it with `@PersistenceUnitExtension` (or `@PersistenceUnitExtension("nameOfYourPU")` for a <<multiple-persistence-units,named persistence unit>>)
 will replace the current Quarkus default implementation `io.quarkus.hibernate.orm.runtime.tenant.DataSourceTenantConnectionResolver`.
 Your custom connection resolver would allow for example to read tenant information from a database and create a connection per tenant at runtime based on it.
 
@@ -1177,7 +1177,7 @@ public static class MyInterceptor extends EmptyInterceptor { // <2>
 <1> Annotate the interceptor implementation with the `@PersistenceUnitExtension` qualifier
 to tell Quarkus it should be used in the default persistence unit.
 +
-For xref:multiple-persistence-units[named persistence units], use `@PersistenceUnitExtension("nameOfYourPU")`
+For <<multiple-persistence-units,named persistence units>>, use `@PersistenceUnitExtension("nameOfYourPU")`
 <2> Either extend `org.hibernate.EmptyInterceptor` or implement `org.hibernate.Interceptor` directly.
 <3> Implement methods as necessary.
 
@@ -1219,5 +1219,5 @@ public class MyStatementInspector implements StatementInspector { // <2>
 <1> Annotate the statement inspector implementation with the `@PersistenceUnitExtension` qualifier
 to tell Quarkus it should be used in the default persistence unit.
 +
-For xref:multiple-persistence-units[named persistence units], use `@PersistenceUnitExtension("nameOfYourPU")`
+For <<multiple-persistence-units,named persistence units>>, use `@PersistenceUnitExtension("nameOfYourPU")`
 <2> Implement `org.hibernate.engine.jdbc.spi.StatementInspector`.

docs/src/main/asciidoc/hibernate-reactive.adoc

@@ -102,7 +102,7 @@ Also, Quarkus will set many Hibernate Reactive configuration settings automatica
 
 WARNING: Configuring Hibernate Reactive using the standard `persistence.xml` configuration file is not supported.
 
-See section xref:hr-configuration-properties[Hibernate Reactive configuration properties] for the list of properties you can set in `{config-file}`.
+See section <<hr-configuration-properties,Hibernate Reactive configuration properties>> for the list of properties you can set in `{config-file}`.
 
 A `Mutiny.SessionFactory` will be created based on the Quarkus `datasource` configuration as long as the Hibernate Reactive extension is listed among your project dependencies.
 

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]