Rework title anchors for gradle docs

Closes gh-26618

Author: philwebb

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/build.gradle

@@ -23,6 +23,8 @@ repositories {
 }
 
 dependencies {
+	asciidoctorExtensions("io.spring.asciidoctor:spring-asciidoctor-extensions-section-ids")
+
 	implementation(project(":spring-boot-project:spring-boot-tools:spring-boot-buildpack-platform"))
 	implementation(project(":spring-boot-project:spring-boot-tools:spring-boot-loader-tools"))
 	implementation("io.spring.gradle:dependency-management-plugin")
@@ -78,7 +80,6 @@ asciidoctor {
 	sources {
 		include "index.adoc"
 	}
-	attributes "stylesheet": "css/style.css"
 }
 
 task asciidoctorPdf(type: org.asciidoctor.gradle.jvm.AsciidoctorTask) {

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

@@ -0,0 +1,48 @@
+integrating-with-actuator=integrating-with-actuator
+integrating-with-actuator-build-info=integrating-with-actuator.build-info
+managing-dependencies=managing-dependencies
+managing-dependencies-dependency-management-plugin=managing-dependencies.dependency-management-plugin
+managing-dependencies-dependency-management-plugin-customizing=managing-dependencies.dependency-management-plugin.customizing
+managing-dependencies-dependency-management-plugin-using-in-isolation=managing-dependencies.dependency-management-plugin.using-in-isolation
+managing-dependencies-dependency-management-plugin-learning-more=managing-dependencies.dependency-management-plugin.learning-more
+managing-dependencies-gradle-bom-support=managing-dependencies.gradle-bom-support
+managing-dependencies-gradle-bom-support-customizing=managing-dependencies.gradle-bom-support.customizing
+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
+packaging-executable=packaging-executable
+packaging-executable-jars=packaging-executable.jars
+packaging-executable-wars=packaging-executable.wars
+packaging-executable-wars-deployable=packaging-executable.wars.deployable
+packaging-executable-and-plain=packaging-executable.and-plain-archives
+packaging-executable-configuring=packaging-executable.configuring
+packaging-executable-configuring-main-class=packaging-executable.configuring.main-class
+packaging-executable-configuring-including-development-only-dependencies=packaging-executable.configuring.including-development-only-dependencies
+packaging-executable-configuring-unpacking=packaging-executable.configuring.unpacking
+packaging-executable-configuring-launch-script=packaging-executable.configuring.launch-script
+packaging-executable-configuring-properties-launcher=packaging-executable.configuring.properties-launcher
+packaging-layered-archives=packaging-executable.configuring.layered-archives
+packaging-layers-configuration=packaging-executable.configuring.layered-archives.configuration
+publishing-your-application=publishing-your-application
+publishing-your-application-maven-publish=publishing-your-application.maven-publish
+publishing-your-application-maven=publishing-your-application.maven
+publishing-your-application-distribution=publishing-your-application.distribution
+reacting-to-other-plugins=reacting-to-other-plugins
+reacting-to-other-plugins-java=reacting-to-other-plugins.java
+reacting-to-other-plugins-kotlin=reacting-to-other-plugins.kotlin
+reacting-to-other-plugins-war=reacting-to-other-plugins.war
+reacting-to-other-plugins-dependency-management=reacting-to-other-plugins.dependency-management
+reacting-to-other-plugins-application=reacting-to-other-plugins.application
+running-your-application=running-your-application
+running-your-application-passing-arguments=running-your-application.passing-arguments
+running-your-application-passing-system-properties=running-your-application.passing-system-properties
+running-your-application-reloading-resources=running-your-application.reloading-resources

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

@@ -1,5 +1,5 @@
 [[getting-started]]
-== Getting Started
+= Getting Started
 To get started with the plugin it needs to be applied to your project.
 
 ifeval::["{spring-boot-artifactory-repo}" == "release"]

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

@@ -40,26 +40,20 @@ Andy Wilkinson, Scott Frederick
 
 
 
-[[introduction]]
-== Introduction
-The Spring Boot Gradle Plugin provides Spring Boot support in https://gradle.org[Gradle].
-It allows you to package executable jar or war archives, run Spring Boot applications, and use the dependency management provided by `spring-boot-dependencies`.
-Spring Boot's Gradle plugin requires Gradle 6.8, 6.9, or 7.x and can be used with Gradle's {gradle-userguide}/configuration_cache.html[configuration cache].
+include::introduction.adoc[leveloffset=+1]
 
-In addition to this user guide, {api-documentation}[API documentation] is also available.
+include::getting-started.adoc[leveloffset=+1]
 
-include::getting-started.adoc[]
+include::managing-dependencies.adoc[leveloffset=+1]
 
-include::managing-dependencies.adoc[]
+include::packaging.adoc[leveloffset=+1]
 
-include::packaging.adoc[]
+include::packaging-oci-image.adoc[leveloffset=+1]
 
-include::packaging-oci-image.adoc[]
+include::publishing.adoc[leveloffset=+1]
 
-include::publishing.adoc[]
+include::running.adoc[leveloffset=+1]
 
-include::running.adoc[]
+include::integrating-with-actuator.adoc[leveloffset=+1]
 
-include::integrating-with-actuator.adoc[]
-
-include::reacting.adoc[]
+include::reacting.adoc[leveloffset=+1]

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/integrating-with-actuator.adoc

@@ -1,10 +1,10 @@
 [[integrating-with-actuator]]
-== Integrating with Actuator
+= Integrating with Actuator
 
 
 
-[[integrating-with-actuator-build-info]]
-=== Generating Build Information
+[[integrating-with-actuator.build-info]]
+== Generating Build Information
 Spring Boot Actuator's `info` endpoint automatically publishes information about your build in the presence of a `META-INF/build-info.properties` file.
 A {build-info-javadoc}[`BuildInfo`] task is provided to generate this file.
 The easiest way to use the task is via the plugin's DSL:

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

@@ -0,0 +1,7 @@
+[[introduction]]
+= Introduction
+The Spring Boot Gradle Plugin provides Spring Boot support in https://gradle.org[Gradle].
+It allows you to package executable jar or war archives, run Spring Boot applications, and use the dependency management provided by `spring-boot-dependencies`.
+Spring Boot's Gradle plugin requires Gradle 6.8, 6.9, or 7.x and can be used with Gradle's {gradle-userguide}/configuration_cache.html[configuration cache].
+
+In addition to this user guide, {api-documentation}[API documentation] is also available.

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/managing-dependencies.adoc

@@ -1,13 +1,13 @@
 [[managing-dependencies]]
-== Managing Dependencies
+= Managing Dependencies
 To manage dependencies in your Spring Boot application, you can either apply the {dependency-management-plugin}[`io.spring.dependency-management`] plugin or use Gradle's native bom support.
 The primary benefit of the former is that it offers property-based customization of managed versions, while using the latter will likely result in faster builds.
 
 
 
-[[managing-dependencies-dependency-management-plugin]]
-=== Managing Dependencies with the Dependency Management Plugin
-When you apply the {dependency-management-plugin}[`io.spring.dependency-management`] plugin, Spring Boot's plugin will automatically <<reacting-to-other-plugins-dependency-management,import the `spring-boot-dependencies` bom>> from the version of Spring Boot that you are using.
+[[managing-dependencies.dependency-management-plugin]]
+== Managing Dependencies with the Dependency Management Plugin
+When you apply the {dependency-management-plugin}[`io.spring.dependency-management`] plugin, Spring Boot's plugin will automatically <<reacting-to-other-plugins.dependency-management,import the `spring-boot-dependencies` bom>> from the version of Spring Boot that you are using.
 This provides a similar dependency management experience to the one that's enjoyed by Maven users.
 For example, it allows you to omit version numbers when declaring dependencies that are managed in the bom.
 To make use of this functionality, declare dependencies in the usual way but omit the version number:
@@ -26,8 +26,8 @@ include::../gradle/managing-dependencies/dependencies.gradle.kts[tags=dependenci
 
 
 
-[[managing-dependencies-dependency-management-plugin-customizing]]
-==== Customizing Managed Versions
+[[managing-dependencies.dependency-management-plugin.customizing]]
+=== Customizing Managed Versions
 The `spring-boot-dependencies` bom that is automatically imported when the dependency management plugin is applied uses properties to control the versions of the dependencies that it manages.
 Browse the {version-properties-appendix}[`Dependency versions Appendix`] in the Spring Boot reference for a complete list of these properties.
 
@@ -51,8 +51,8 @@ Overriding versions may cause compatibility issues and should be done with care.
 
 
 
-[[managing-dependencies-dependency-management-plugin-using-in-isolation]]
-==== Using Spring Boot's Dependency Management in Isolation
+[[managing-dependencies.dependency-management-plugin.using-in-isolation]]
+=== Using Spring Boot's Dependency Management in Isolation
 Spring Boot's dependency management can be used in a project without applying Spring Boot's plugin to that project.
 The `SpringBootPlugin` class provides a `BOM_COORDINATES` constant that can be used to import the bom without having to know its group ID, artifact ID, or version.
 
@@ -126,14 +126,14 @@ include::../gradle/managing-dependencies/configure-bom-with-plugins.gradle.kts[t
 
 
 
-[[managing-dependencies-dependency-management-plugin-learning-more]]
-==== Learning More
+[[managing-dependencies.dependency-management-plugin.learning-more]]
+=== Learning More
 To learn more about the capabilities of the dependency management plugin, please refer to its {dependency-management-plugin-documentation}[documentation].
 
 
 
-[[managing-dependencies-gradle-bom-support]]
-=== Managing Dependencies with Gradle's Bom Support
+[[managing-dependencies.gradle-bom-support]]
+== Managing Dependencies with Gradle's Bom Support
 Gradle allows a bom to be used to manage a project's versions by declaring it as a `platform` or `enforcedPlatform` dependency.
 A `platform` dependency treats the versions in the bom as recommendations and other versions and constraints in the dependency graph may cause a version of a dependency other than that declared in the bom to be used.
 An `enforcedPlatform` dependency treats the versions in the bom as requirements and they will override any other version found in the dependency graph.
@@ -157,8 +157,8 @@ As a result, in may be necessary to declare the same dependency in more than one
 
 
 
-[[managing-dependencies-gradle-bom-support-customizing]]
-==== Customizing Managed Versions
+[[managing-dependencies.gradle-bom-support.customizing]]
+=== Customizing Managed Versions
 When using Gradle's bom support, you cannot use the properties from `spring-boot-dependencies` to control the versions of the dependencies that it manages.
 Instead, you must use one of the mechanisms that Gradle provides.
 One such mechanism is a resolution strategy.

spring-boot-project/spring-boot-tools/spring-boot-gradle-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 `bootBuildImage` task.
 
@@ -8,13 +8,13 @@ See the {buildpacks-reference}/reference/spec/platform-api/#users[CNB specificat
 
 The task is automatically created when the `java` or `war` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`].
 
-NOTE: The `bootBuildImage` task can not be used with a <<packaging-executable-configuring-launch-script, fully executable Spring Boot archive>> that includes a launch script.
+NOTE: The `bootBuildImage` task can not be used with a <<packaging-executable.configuring.launch-script, fully executable Spring Boot archive>> that includes a launch script.
 Disable launch script configuration in the `bootJar` task when building a jar file that is intended to be used with `bootBuildImage`.
 
 
 
-[[build-image-docker-daemon]]
-=== Docker Daemon
+[[build-image.docker-daemon]]
+== Docker Daemon
 The `bootBuildImage` task 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.
@@ -53,12 +53,12 @@ The following table summarizes the available properties:
 | 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` properties are stored in a private Docker image registry that requires authentication, the authentication credentials can be provided using `docker.builderRegistry` properties.
 
 If the generated Docker image is to be published to a Docker image registry, the authentication credentials can be provided using `docker.publishRegistry` properties.
@@ -87,12 +87,12 @@ The following table summarizes the available properties 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.
@@ -176,17 +176,17 @@ Where `<options>` can contain:
 
 NOTE: The plugin detects the target Java compatibility of the project using the JavaPlugin's `targetCompatibility` 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.
 
 
 
-[[build-image-examples]]
-=== Examples
+[[build-image.examples]]
+== Examples
 
 
 
-[[build-image-example-custom-image-builder]]
-==== Custom Image Builder and Run Image
+[[build-image.examples.custom-image-builder]]
+=== Custom Image Builder and Run Image
 If you need to customize the builder used to create the image or the run image used to launch the built image, configure the task as shown in the following example:
 
 [source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
@@ -212,8 +212,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, those can be set using the `environment` property.
 
 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:
@@ -247,8 +247,8 @@ include::../gradle/packaging/boot-build-image-env-proxy.gradle.kts[tags=env]
 
 
 
-[[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.
 
@@ -268,8 +268,8 @@ include::../gradle/packaging/boot-build-image-env-runtime.gradle.kts[tags=env-ru
 
 
 
-[[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 `name` and the `version` of the project, something like `docker.io/library/${project.name}:${project.version}`.
 You can take control over the name by setting task properties, as shown in the following example:
 
@@ -297,8 +297,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.
@@ -347,8 +347,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` properties.
 
 [source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
@@ -372,8 +372,8 @@ The publish option can be specified on the command line as well, as shown in thi
 
 
 
-[[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` properties as shown in the following example:
 
 [source,groovy,indent=0,subs="verbatim,attributes",role="primary"]