Rework title anchors for maven docs

Closes gh-26617

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

@@ -94,7 +94,7 @@ public class DocumentPluginGoals extends DefaultTask {
 			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 @@ public class DocumentPluginGoals extends DefaultTask {
 				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 @@ public class DocumentPluginGoals extends DefaultTask {
 				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 @@ public class DocumentPluginGoals extends DefaultTask {
 			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]

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

@@ -1,5 +1,5 @@
-[[repackage]]
-== Packaging Executable Archives
+[[packaging]]
+= Packaging Executable Archives
 The plugin can create executable archives (jar files and war files) that contain all of an application's dependencies and can then be run with `java -jar`.
 
 Packaging an executable archive is performed by the `repackage` goal, as shown in the following example:
@@ -12,7 +12,7 @@ include::../maven/packaging/repackage-pom.xml[tags=repackage]
 TIP: If you are using `spring-boot-starter-parent`, such execution is already pre-configured with a `repackage` execution ID so that only the plugin definition should be added.
 
 The example above repackages a `jar` or `war` archive that is built during the package phase of the Maven lifecycle, including any `provided` dependencies that are defined in the project.
-If some of these dependencies need to be excluded, you can use one of the `exclude` options; see the <<repackage-example-exclude-dependency,dependency exclusion>> for more details.
+If some of these dependencies need to be excluded, you can use one of the `exclude` options; see the <<packaging.examples.exclude-dependency,dependency exclusion>> for more details.
 
 The original (i.e. non-executable) artifact is renamed to `.original` by default but it is also possible to keep the original artifact using a custom classifier.
 
@@ -39,8 +39,8 @@ The `layout` property defaults to a value determined by the archive type (`jar`
 
 
 
-[[repackage-layers]]
-=== Layered Jar or War
+[[packaging.layers]]
+== Layered Jar or War
 A repackaged jar contains the application's classes and dependencies in `BOOT-INF/classes` and `BOOT-INF/lib` respectively.
 Similarly, an executable war contains the application's classes in `WEB-INF/classes` and dependencies in `WEB-INF/lib` and `WEB-INF/lib-provided`.
 For cases where a docker image needs to be built from the contents of a jar or war, it's useful to be able to separate these directories further so that they can be written into distinct layers.
@@ -71,8 +71,8 @@ include::../maven/packaging/disable-layers-pom.xml[tags=disable-layers]
 
 
 
-[[repackage-layers-configuration]]
-==== Custom Layers Configuration
+[[packaging.layers.configuration=]]
+=== Custom Layers Configuration
 Depending on your application, you may want to tune how layers are created and add new ones.
 This can be done using a separate configuration file that should be registered as shown below:
 
@@ -123,13 +123,13 @@ include::goals/repackage.adoc[leveloffset=+1]
 
 
 
-[[repackage-examples]]
-=== Examples
+[[packaging.examples]]
+== Examples
 
 
 
-[[repackage-example-custom-classifier]]
-==== Custom Classifier
+[[packaging.examples.custom-classifier]]
+=== Custom Classifier
 By default, the `repackage` goal replaces the original artifact with the repackaged one.
 That is a sane behavior for modules that represent an application but if your module is used as a dependency of another module, you need to provide a classifier for the repackaged one.
 The reason for that is that application classes are packaged in `BOOT-INF/classes` so that the dependent module cannot load a repackaged jar's classes.
@@ -170,8 +170,8 @@ include::../maven/packaging/jar-plugin-first-pom.xml[tags=jar-plugin-first]
 
 
 
-[[repackage-example-custom-name]]
-==== Custom Name
+[[packaging.examples.custom-name]]
+=== Custom Name
 If you need the repackaged jar to have a different local name than the one defined by the `artifactId` attribute of the project, use the standard `finalName`, as shown in the following example:
 
 [source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
@@ -183,8 +183,8 @@ This configuration will generate the repackaged artifact in `target/my-app.jar`.
 
 
 
-[[repackage-example-local-artifact]]
-==== Local Repackaged Artifact
+[[packaging.examples.local-artifact]]
+=== Local Repackaged Artifact
 By default, the `repackage` goal replaces the original artifact with the executable one.
 If you need to only deploy the original jar and yet be able to run your app with the regular file name, configure the plugin as follows:
 
@@ -198,8 +198,8 @@ Only the original one will be installed/deployed.
 
 
 
-[[repackage-example-custom-layout]]
-==== Custom Layout
+[[packaging.examples.custom-layout]]
+=== Custom Layout
 Spring Boot repackages the jar file for this project using a custom layout factory defined in the additional jar file, provided as a dependency to the build plugin:
 
 [source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
@@ -214,8 +214,8 @@ Layout factories are always ignored if an explicit <<goals-repackage-parameters-
 
 
 
-[[repackage-example-exclude-dependency]]
-==== Dependency Exclusion
+[[packaging.examples.exclude-dependency]]
+=== Dependency Exclusion
 By default, both the `repackage` and the `run` goals will include any `provided` dependencies that are defined in the project.
 A Spring Boot project should consider `provided` dependencies as "container" dependencies that are required to run the application.
 
@@ -243,8 +243,8 @@ include::../maven/packaging/exclude-artifact-group-pom.xml[tags=exclude-artifact
 
 
 
-[[repackage-layered-archive-tools]]
-==== Layered Archive Tools
+[[packaging.examples.layered-archive-tools]]
+=== Layered Archive Tools
 When a layered jar or war is created, the `spring-boot-jarmode-layertools` jar will be added as a dependency to your archive.
 With this jar on the classpath, you can launch your application in a special mode which allows the bootstrap code to run something entirely different from your application, for example, something that extracts the layers.
 If you wish to exclude this dependency, you can do so in the following manner:
@@ -256,8 +256,8 @@ include::../maven/packaging/exclude-dependency-pom.xml[tags=exclude-dependency]
 
 
 
-[[repackage-layered-archive-additional-layers]]
-==== Custom Layers Configuration
+[[packaging.examples.custom-layers-configuration]]
+=== Custom Layers Configuration
 The default setup splits dependencies into snapshot and non-snapshot, however, you may have more complex rules.
 For example, you may want to isolate company-specific dependencies of your project in a dedicated layer.
 The following `layers.xml` configuration shown one such setup:

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

@@ -1,5 +1,5 @@
 [[run]]
-== Running your Application with Maven
+= Running your Application with Maven
 The plugin includes a run goal which can be used to launch your application from the command line, as shown in the following example:
 
 [indent=0]
@@ -7,13 +7,13 @@ The plugin includes a run goal which can be used to launch your application from
 	$ mvn spring-boot:run
 ----
 
-Application arguments can be specified using the `arguments` parameter, see <<run-example-application-arguments,using application arguments>> for more details.
+Application arguments can be specified using the `arguments` parameter, see <<run.examples.using-application-arguments,using application arguments>> for more details.
 
 By default the application is executed in a forked process and setting properties on the command-line will not affect the application.
-If you need to specify some JVM arguments (i.e. for debugging purposes), you can use the `jvmArguments` parameter, see <<run-example-debug,Debug the application>> for more details.
-There is also explicit support for <<run-example-system-properties,system properties>> and <<run-example-environment-variables,environment variables>>.
+If you need to specify some JVM arguments (i.e. for debugging purposes), you can use the `jvmArguments` parameter, see <<run.examples.debug,Debug the application>> for more details.
+There is also explicit support for <<run.examples.system-properties,system properties>> and <<run.examples.environment-variables,environment variables>>.
 
-As enabling a profile is quite common, there is dedicated `profiles` property that offers a shortcut for `-Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev"`, see <<run-example-active-profiles,Specify active profiles>>.
+As enabling a profile is quite common, there is dedicated `profiles` property that offers a shortcut for `-Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev"`, see <<run.examples.specify-active-profiles,Specify active profiles>>.
 
 Although this is not recommended, it is possible to execute the application directly from the Maven JVM by disabling the `fork` property.
 Doing so means that the `jvmArguments`, `systemPropertyVariables`, `environmentVariables` and `agents` options are ignored.
@@ -54,7 +54,7 @@ It is also a helpful way of allowing your front end developers to work without n
 NOTE: A side effect of using this feature is that filtering of resources at build time will not work.
 
 In order to be consistent with the `repackage` goal, the `run` goal builds the classpath in such a way that any dependency that is excluded in the plugin's configuration gets excluded from the classpath as well.
-For more details, see <<repackage-example-exclude-dependency,the dedicated example>>.
+For more details, see <<packaging.examples.exclude-dependency,the dedicated example>>.
 
 Sometimes it is useful to include test dependencies when running the application.
 For example, if you want to run your application in a test mode that uses stub classes.
@@ -66,13 +66,13 @@ include::goals/run.adoc[leveloffset=+1]
 
 
 
-[[run-examples]]
-=== Examples
+[[run.examples]]
+== Examples
 
 
 
-[[run-example-debug]]
-==== Debug the Application
+[[run.examples.debug]]
+=== Debug the Application
 By default, the `run` goal runs your application in a forked process.
 If you need to debug it, you should add the necessary JVM arguments to enable remote debugging.
 The following configuration suspend the process until a debugger has joined on port 5005:
@@ -91,8 +91,8 @@ These arguments can be specified on the command line as well, make sure to wrap
 
 
 
-[[run-example-system-properties]]
-==== Using System Properties
+[[run.examples.system-properties]]
+=== Using System Properties
 System properties can be specified using the `systemPropertyVariables` attribute.
 The following example sets `property1` to `test` and `property2` to 42:
 
@@ -117,8 +117,8 @@ In the following example, the value for `property1` is `overridden`:
 
 
 
-[[run-example-environment-variables]]
-==== Using Environment Variables
+[[run.examples.environment-variables]]
+=== Using Environment Variables
 Environment variables can be specified using the `environmentVariables` attribute.
 The following example sets the 'ENV1', 'ENV2', 'ENV3', 'ENV4' env variables:
 
@@ -137,8 +137,8 @@ Environment variables defined this way take precedence over existing values.
 
 
 
-[[run-example-application-arguments]]
-==== Using Application Arguments
+[[run.examples.using-application-arguments]]
+=== Using Application Arguments
 Application arguments can be specified using the `arguments` attribute.
 The following example sets two arguments: `property1` and `property2=42`:
 
@@ -158,8 +158,8 @@ In the following example, two arguments are available: `property1` and `property
 
 
 
-[[run-example-active-profiles]]
-==== Specify Active Profiles
+[[run.examples.specify-active-profiles]]
+=== Specify Active Profiles
 The active profiles to use for a particular application can be specified using the `profiles` argument.
 
 The following configuration enables the `local` and `dev` profiles:

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

@@ -1,5 +1,5 @@
 [[using]]
-== Using the Plugin
+= Using the Plugin
 Maven users can inherit from the `spring-boot-starter-parent` project to obtain sensible defaults.
 The parent project provides the following features:
 
@@ -17,8 +17,8 @@ NOTE: Since the `application.properties` and `application.yml` files accept Spri
 
 
 
-[[using-parent-pom]]
-=== Inheriting the Starter Parent POM
+[[using.parent-pom]]
+== Inheriting the Starter Parent POM
 To configure your project to inherit from the `spring-boot-starter-parent`, set the `parent` as follows:
 
 [source,xml,indent=0,subs="verbatim,quotes,attributes"]
@@ -46,8 +46,8 @@ Browse the {version-properties-appendix}[`Dependency versions Appendix`] in the
 
 
 
-[[using-import]]
-=== Using Spring Boot without the Parent POM
+[[using.import]]
+== Using Spring Boot without the Parent POM
 There may be reasons for you not to inherit from the `spring-boot-starter-parent` POM.
 You may have your own corporate standard parent that you need to use or you may prefer to explicitly declare all your Maven configuration.
 
@@ -69,8 +69,8 @@ include::../maven/using/no-starter-parent-override-dependencies-pom.xml[tags=no-
 
 
 
-[[using-overriding-command-line]]
-=== Overriding settings on the command-line
+[[using.overriding-command-line]]
+== Overriding settings on the command-line
 The plugin offers a number of user properties, starting with `spring-boot`, to let you customize the configuration from the command-line.
 
 For instance, you could tune the profiles to enable when running the application as follows: