Rework title anchors for maven docs

Closes gh-26617

Author: philwebb

buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java

@@ -94,7 +94,7 @@ private void documentMojo(Plugin plugin, Mojo mojo) throws IOException {
 			writer.println();
 			writer.println();
 			writer.printf("[[%s]]%n", sectionId);
-			writer.printf("== `%s:%s`%n", plugin.getGoalPrefix(), mojo.getGoal());
+			writer.printf("= `%s:%s`%n", plugin.getGoalPrefix(), mojo.getGoal());
 			writer.printf("`%s:%s:%s`%n", plugin.getGroupId(), plugin.getArtifactId(), plugin.getVersion());
 			writer.println();
 			writer.println(mojo.getDescription());
@@ -108,7 +108,7 @@ private void documentMojo(Plugin plugin, Mojo mojo) throws IOException {
 				writer.println();
 				writer.println();
 				writer.printf("[[%s-required]]%n", parametersSectionId);
-				writer.println("=== Required parameters");
+				writer.println("== Required parameters");
 				writeParametersTable(writer, detailsSectionId, requiredParameters);
 			}
 			List<Parameter> optionalParameters = parameters.stream().filter((parameter) -> !parameter.isRequired())
@@ -117,13 +117,13 @@ private void documentMojo(Plugin plugin, Mojo mojo) throws IOException {
 				writer.println();
 				writer.println();
 				writer.printf("[[%s-optional]]%n", parametersSectionId);
-				writer.println("=== Optional parameters");
+				writer.println("== Optional parameters");
 				writeParametersTable(writer, detailsSectionId, optionalParameters);
 			}
 			writer.println();
 			writer.println();
 			writer.printf("[[%s]]%n", detailsSectionId);
-			writer.println("=== Parameter details");
+			writer.println("== Parameter details");
 			writeParameterDetails(writer, parameters, detailsSectionId);
 		}
 	}
@@ -155,7 +155,7 @@ private void writeParameterDetails(PrintWriter writer, List<Parameter> parameter
 			writer.println();
 			writer.println();
 			writer.printf("[[%s-%s]]%n", sectionId, name);
-			writer.printf("==== `%s`%n", name);
+			writer.printf("=== `%s`%n", name);
 			writer.println(parameter.getDescription());
 			writer.println();
 			writer.println("[cols=\"10h,90\"]");

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/anchor-rewrite.properties

@@ -0,0 +1,46 @@
+
+build-info=?
+getting-started=?
+goals=?
+help=?
+spring-boot-maven-plugin-documentation=?
+introduction=?.?
+integration-tests=integration-tests
+integration-tests-no-starter-parent=integration-tests.no-starter-parent
+integration-tests-example=integration-tests.examples
+integration-tests-example-random-port=integration-tests.examples.random-port
+integration-tests-example-jmx-port=integration-tests.examples.jmx-port
+integration-tests-example-skip=integration-tests.examples.skip
+build-image=build-image
+build-image-docker-daemon=build-image.docker-daemon
+build-image-docker-registry=build-image.docker-registry
+build-image-customization=build-image.customization
+build-image-examples=build-image.examples
+build-image-example-custom-image-builder=build-image.examples.custom-image-builder
+build-image-example-builder-configuration=build-image.examples.builder-configuration
+build-image-example-runtime-jvm-configuration=build-image.examples.runtime-jvm-configuration
+build-image-example-custom-image-name=build-image.examples.custom-image-name
+build-image-example-buildpacks=build-image.examples.buildpacks
+build-image-example-publish=build-image.examples.publish
+build-image-example-docker=build-image.examples.docker
+repackage=packaging
+repackage-layers=packaging.layers
+repackage-layers-configuration=packaging.layers.configuration=repackage-examples=packaging.examples
+repackage-example-custom-classifier=packaging.examples.custom-classifier
+repackage-example-custom-name=packaging.examples.custom-name
+repackage-example-local-artifact=packaging.examples.local-artifact
+repackage-example-custom-layout=packaging.examples.custom-layout
+repackage-example-exclude-dependency=packaging.examples.exclude-dependency
+repackage-layered-archive-tools=packaging.examples.layered-archive-tools
+repackage-layered-archive-additional-layers=packaging.examples.custom-layers-configuration
+run=run
+run-examples=run.examples
+run-example-debug=run.examples.debug
+run-example-system-properties=run.examples.system-properties
+run-example-environment-variables=run.examples.environment-variables
+run-example-application-arguments=run.examples.using-application-arguments
+run-example-active-profiles=run.examples.specify-active-profiles
+using=using
+using-parent-pom=using.parent-pom
+using-import=using.import
+using-overriding-command-line=using.overriding-command-line

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/build-info.adoc

@@ -1,5 +1,5 @@
 [[build-info]]
-== Integrating with Actuator
+= Integrating with Actuator
 Spring Boot Actuator displays build-related information if a `META-INF/build-info.properties` file is present.
 The `build-info` goal generates such file with the coordinates of the project and the build time.
 It also allows you to add an arbitrary number of additional properties, as shown in the following example:

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/getting-started.adoc

@@ -1,5 +1,5 @@
 [[getting-started]]
-== Getting Started
+= Getting Started
 To use the Spring Boot Maven Plugin, include the appropriate XML in the `plugins` section of your `pom.xml`, as shown in the following example:
 
 [source,xml,indent=0,subs="verbatim,attributes",tabsize=4]

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/goals.adoc

@@ -1,5 +1,5 @@
 [[goals]]
-== Goals
+= Goals
 The Spring Boot Plugin has the following goals:
 
 include::goals/overview.adoc[]

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/help.adoc

@@ -1,5 +1,5 @@
 [[help]]
-== Help Information
+= Help Information
 The `help` goal is a standard goal that  displays information on the capabilities of the plugin.
 
 include::goals/help.adoc[leveloffset=+1]

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc

@@ -20,25 +20,22 @@ Stephane Nicoll, Andy Wilkinson, Scott Frederick
 
 
 
-[[introduction]]
-== Introduction
-The Spring Boot Maven Plugin provides Spring Boot support in https://maven.org[Apache Maven].
-It allows you to package executable jar or war archives, run Spring Boot applications, generate build information and start your Spring Boot application prior to running integration tests.
+include::introduction.adoc[leveloffset=+1]
 
-include::getting-started.adoc[]
+include::getting-started.adoc[leveloffset=+1]
 
-include::using.adoc[]
+include::using.adoc[leveloffset=+1]
 
-include::goals.adoc[]
+include::goals.adoc[leveloffset=+1]
 
-include::packaging.adoc[]
+include::packaging.adoc[leveloffset=+1]
 
-include::packaging-oci-image.adoc[]
+include::packaging-oci-image.adoc[leveloffset=+1]
 
-include::running.adoc[]
+include::running.adoc[leveloffset=+1]
 
-include::integration-tests.adoc[]
+include::integration-tests.adoc[leveloffset=+1]
 
-include::build-info.adoc[]
+include::build-info.adoc[leveloffset=+1]
 
-include::help.adoc[]
+include::help.adoc[leveloffset=+1]

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/integration-tests.adoc

@@ -1,5 +1,5 @@
 [[integration-tests]]
-== Running Integration Tests
+= Running Integration Tests
 While you may start your Spring Boot application very easily from your test (or test suite) itself, it may be desirable to handle that in the build itself.
 To make sure that the lifecycle of your Spring Boot application is properly managed around your integration tests, you can use the `start` and `stop` goals, as shown in the following example:
 
@@ -11,14 +11,14 @@ include::../maven/integration-tests/pom.xml[tags=integration-tests]
 Such setup can now use the https://maven.apache.org/surefire/maven-failsafe-plugin[failsafe-plugin] to run your integration tests as you would expect.
 
 NOTE: By default, the application is started in a separate process and JMX is used to communicate with the application.
-If you need to configure the JMX port, see <<integration-tests-example-jmx-port,the dedicated example>>.
+If you need to configure the JMX port, see <<integration-tests.examples.jmx-port,the dedicated example>>.
 
-You could also configure a more advanced setup to skip the integration tests when a specific property has been set, see <<integration-tests-example-skip,the dedicated example>>.
+You could also configure a more advanced setup to skip the integration tests when a specific property has been set, see <<integration-tests.examples.skip,the dedicated example>>.
 
 
 
-[[integration-tests-no-starter-parent]]
-=== Using Failsafe Without Spring Boot's Parent POM
+[[integration-tests.no-starter-parent]]
+== Using Failsafe Without Spring Boot's Parent POM
 Spring Boot's Parent POM, `spring-boot-starter-parent`, configures Failsafe's `<classesDirectory>` to be `${project.build.outputDirectory}`.
 Without this configuration, which causes Failsafe to use the compiled classes rather than the repackaged jar, Failsafe cannot load your application's classes.
 If you are not using the parent POM, you should configure Failsafe in the same way, as shown in the following example:
@@ -34,13 +34,13 @@ include::goals/stop.adoc[leveloffset=+1]
 
 
 
-[[integration-tests-example]]
-=== Examples
+[[integration-tests.examples]]
+== Examples
 
 
 
-[[integration-tests-example-random-port]]
-==== Random Port for Integration Tests
+[[integration-tests.examples.random-port]]
+=== Random Port for Integration Tests
 One nice feature of the Spring Boot test integration is that it can allocate a free port for the web application.
 When the `start` goal of the plugin is used, the Spring Boot application is started separately, making it difficult to pass the actual port to the integration test itself.
 
@@ -55,8 +55,8 @@ You can now retrieve the `test.server.port` system property in any of your integ
 
 
 
-[[integration-tests-example-jmx-port]]
-==== Customize JMX port
+[[integration-tests.examples.jmx-port]]
+=== Customize JMX port
 The `jmxPort` property allows to customize the port the plugin uses to communicate with the Spring Boot application.
 
 This example shows how you can customize the port in case `9001` is already used:
@@ -70,8 +70,8 @@ TIP: If you need to configure the JMX port, make sure to do so in the global con
 
 
 
-[[integration-tests-example-skip]]
-==== Skip Integration Tests
+[[integration-tests.examples.skip]]
+=== Skip Integration Tests
 The `skip` property allows to skip the execution of the Spring Boot maven plugin altogether.
 
 This example shows how you can skip integration tests with a command-line property and still make sure that the `repackage` goal runs:

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/introduction.adoc

@@ -0,0 +1,4 @@
+[[introduction]]
+= Introduction
+The Spring Boot Maven Plugin provides Spring Boot support in https://maven.org[Apache Maven].
+It allows you to package executable jar or war archives, run Spring Boot applications, generate build information and start your Spring Boot application prior to running integration tests.

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc

@@ -1,5 +1,5 @@
 [[build-image]]
-== Packaging OCI Images
+= Packaging OCI Images
 The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from a jar or war file using https://buildpacks.io/[Cloud Native Buildpacks] (CNB).
 Images can be built using the `build-image` goal.
 
@@ -14,13 +14,13 @@ It is possible to automate the creation of an image whenever the `package` phase
 include::../maven/packaging-oci-image/pom.xml[tags=packaging-oci-image]
 ----
 
-TIP: While the buildpack runs from an <<repackage,executable archive>>, it is not necessary to execute the `repackage` goal first as the executable archive is created automatically if necessary.
+TIP: While the buildpack runs from an <<packaging,executable archive>>, it is not necessary to execute the `repackage` goal first as the executable archive is created automatically if necessary.
 When the `build-image` repackages the application, it applies the same settings as the `repackage` goal would, i.e. dependencies can be excluded using one of the exclude options, and Devtools is automatically excluded by default (you can control that using the `excludeDevtools` property).
 
 
 
-[[build-image-docker-daemon]]
-=== Docker Daemon
+[[build-image.docker-daemon]]
+== Docker Daemon
 The `build-image` goal requires access to a Docker daemon.
 By default, it will communicate with a Docker daemon over a local connection.
 This works with https://docs.docker.com/install/[Docker Engine] on all supported platforms without configuration.
@@ -59,12 +59,12 @@ The following table summarizes the available parameters:
 | Path to certificate and key files for HTTPS (required if `tlsVerify` is `true`, ignored otherwise)
 |===
 
-For more details, see also <<build-image-example-docker,examples>>.
+For more details, see also <<build-image.examples.docker,examples>>.
 
 
 
-[[build-image-docker-registry]]
-=== Docker Registry
+[[build-image.docker-registry]]
+== Docker Registry
 If the Docker images specified by the `builder` or `runImage` parameters are stored in a private Docker image registry that requires authentication, the authentication credentials can be provided using `docker.builderRegistry` parameters.
 
 If the generated Docker image is to be published to a Docker image registry, the authentication credentials can be provided using `docker.publishRegistry` parameters.
@@ -93,12 +93,12 @@ The following table summarizes the available parameters for `docker.builderRegis
 | Identity token for the Docker image registry user. Required for token authentication.
 |===
 
-For more details, see also <<build-image-example-docker,examples>>.
+For more details, see also <<build-image.examples.docker,examples>>.
 
 
 
-[[build-image-customization]]
-=== Image Customizations
+[[build-image.customization]]
+== Image Customizations
 The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image.
 The builder includes multiple {buildpacks-reference}/concepts/components/buildpack[buildpacks] that can inspect the application to influence the generated image.
 By default, the plugin chooses a builder image.
@@ -182,21 +182,21 @@ Where `<options>` can contain:
 
 NOTE: The plugin detects the target Java compatibility of the project using the compiler's plugin configuration or the `maven.compiler.target` property.
 When using the default Paketo builder and buildpacks, the plugin instructs the buildpacks to install the same Java version.
-You can override this behaviour as shown in the <<build-image-example-builder-configuration,builder configuration>> examples.
+You can override this behaviour as shown in the <<build-image.examples.builder-configuration,builder configuration>> examples.
 
-For more details, see also <<build-image-examples,examples>>.
+For more details, see also <<build-image.examples,examples>>.
 
 include::goals/build-image.adoc[leveloffset=+1]
 
 
 
-[[build-image-examples]]
-=== Examples
+[[build-image.examples]]
+== Examples
 
 
 
-[[build-image-example-custom-image-builder]]
-==== Custom Image Builder
+[[build-image.examples.custom-image-builder]]
+=== Custom Image Builder
 If you need to customize the builder used to create the image or the run image used to launch the built image, configure the plugin as shown in the following example:
 
 [source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
@@ -215,8 +215,8 @@ The builder and run image can be specified on the command line as well, as shown
 
 
 
-[[build-image-example-builder-configuration]]
-==== Builder Configuration
+[[build-image.examples.builder-configuration]]
+=== Builder Configuration
 If the builder exposes configuration options using environment variables, those can be set using the `env` attributes.
 
 The following is an example of {paketo-java-reference}/#configuring-the-jvm-version[configuring the JVM version] used by the Paketo Java buildpacks at build time:
@@ -236,8 +236,8 @@ include::../maven/packaging-oci-image/paketo-pom.xml[tags=paketo]
 
 
 
-[[build-image-example-runtime-jvm-configuration]]
-==== Runtime JVM Configuration
+[[build-image.examples.runtime-jvm-configuration]]
+=== Runtime JVM Configuration
 Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable.
 The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container.
 
@@ -250,8 +250,8 @@ include::../maven/packaging-oci-image/runtime-jvm-configuration-pom.xml[tags=run
 
 
 
-[[build-image-example-custom-image-name]]
-==== Custom Image Name
+[[build-image.examples.custom-image-name]]
+=== Custom Image Name
 By default, the image name is inferred from the `artifactId` and the `version` of the project, something like `docker.io/library/${project.artifactId}:${project.version}`.
 You can take control over the name, as shown in the following example:
 
@@ -272,8 +272,8 @@ The image name can be specified on the command line as well, as shown in this ex
 
 
 
-[[build-image-example-buildpacks]]
-==== Buildpacks
+[[build-image.examples.buildpacks]]
+=== Buildpacks
 By default, the builder will use buildpacks included in the builder image and apply them in a pre-defined order.
 An alternative set of buildpacks can be provided to apply buildpacks that are not included in the builder, or to change the order of included buildpacks.
 When one or more buildpacks are provided, only the specified buildpacks will be applied.
@@ -315,8 +315,8 @@ An OCI image containing a https://buildpacks.io/docs/buildpack-author-guide/pack
 
 
 
-[[build-image-example-publish]]
-==== Image Publishing
+[[build-image.examples.publish]]
+=== Image Publishing
 The generated image can be published to a Docker registry by enabling a `publish` option and configuring authentication for the registry using `docker.publishRegistry` parameters.
 
 [source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
@@ -333,8 +333,8 @@ The `publish` option can be specified on the command line as well, as shown in t
 
 
 
-[[build-image-example-docker]]
-==== Docker Configuration
+[[build-image.examples.docker]]
+=== Docker Configuration
 If you need the plugin to communicate with the Docker daemon using a remote connection instead of the default local connection, the connection details can be provided using `docker` parameters as shown in the following example:
 
 [source,xml,indent=0,subs="verbatim,attributes",tabsize=4]