apache · sanjana2505006 · Jan 24, 2026 · Feb 4, 2026 · Feb 23, 2026
diff --git a/grails-doc/src/en/guide/conf/config/builtInOptions.adoc b/grails-doc/src/en/guide/conf/config/builtInOptions.adoc
@@ -17,11 +17,13 @@ specific language governing permissions and limitations
 under the License.
 ////
 
+= Built in options
+
 Grails has a set of core settings that are worth knowing about. Their defaults are suitable for most projects, but it's important to understand what they do because you may need one or more of them later.
 
 
 
-=== Runtime settings
+== Runtime settings
 
 
 On the runtime front, i.e. `grails-app/conf/application.yml`, there are quite a few more core settings:

diff --git a/grails-doc/src/en/guide/deployment/deploymentContainer.adoc b/grails-doc/src/en/guide/deployment/deploymentContainer.adoc
@@ -20,7 +20,9 @@ under the License.
 Grails apps can be deployed to a Servlet Container or Application Server.
 
 
-=== WAR file
+= Container Deployment (e.g. Tomcat)
+
+== WAR file
 
 
 A common approach to Grails application deployment in production is to deploy to an existing Servlet container via a WAR file. Containers allow multiple applications to be deployed on the same port with different paths.

diff --git a/grails-doc/src/en/guide/deployment/deploymentStandalone.adoc b/grails-doc/src/en/guide/deployment/deploymentStandalone.adoc
@@ -19,7 +19,9 @@ under the License.
 
 
 
-=== "grails run-app"
+= Standalone
+
+== "grails run-app"
 
 
 You should be very familiar with this approach by now, since it is the most common method of running an application during the development phase. An embedded Tomcat server is launched that loads the web application from the development sources, thus allowing it to pick up any changes to application files.
@@ -39,7 +41,7 @@ You can specify an environment supplying `grails.env` system property.
 
 `./gradlew -Dgrails.env=prod bootRun`
 
-=== Runnable WAR or JAR file
+== Runnable WAR or JAR file
 
 Another way to deploy in Grails 3.0 or above is to use the new support for runnable JAR or WAR files. To create runnable archives, run `grails package`:
 
@@ -59,12 +61,12 @@ You can then run either the WAR file or the JAR using your Java installation:
 java -Dgrails.env=prod -jar build/libs/mywar-0.1.war    (or .jar)
 ----
 
-=== A TAR/ZIP distribution
+== A TAR/ZIP distribution
 
 WARNING: Note: TAR/ZIP distribution assembly has been removed from Grails 3.1.
 
 
-=== "./gradlew bootRun"
+== "./gradlew bootRun"
 
 
 You should be very familiar with this approach by now, since it is the most common method of running an application during the development phase. An embedded Tomcat server is launched that loads the web application from the development sources, thus allowing it to pick up any changes to application files.
@@ -84,7 +86,7 @@ You can specify an environment supplying `grails.env` system property.
 
 `./gradlew -Dgrails.env=prod bootRun`
 
-=== Runnable WAR or JAR file
+== Runnable WAR or JAR file
 
 Another way to deploy in Grails 3.0 or above is to use the new support for runnable JAR or WAR files. To create runnable archives, run `grails package`:
 
@@ -104,6 +106,6 @@ You can then run either the WAR file or the JAR using your Java installation:
 java -Dgrails.env=prod -jar build/libs/mywar-0.1.war    (or .jar)
 ----
 
-=== A TAR/ZIP distribution
+== A TAR/ZIP distribution
 
 WARNING: Note: TAR/ZIP distribution assembly has been removed from Grails 3.1.
diff --git a/grails-doc/src/en/guide/index.adoc b/grails-doc/src/en/guide/index.adoc
@@ -146,9 +146,7 @@ include::conf/config.adoc[]
 include::conf/config/ymlPropertyOptions.adoc[]
 
 [[builtInOptions]]
-==== Built in options
-
-include::conf/config/builtInOptions.adoc[]
+include::conf/config/builtInOptions.adoc[leveloffset=+3]
 
 [[logging]]
 ==== Logging
@@ -961,9 +959,7 @@ include::testing/unitTesting.adoc[]
 include::testing/unitTesting/unitTestingControllers.adoc[]
 
 [[unitTestingTagLibraries]]
-==== Unit Testing Tag Libraries
-
-include::testing/unitTesting/unitTestingTagLibraries.adoc[]
+include::testing/unitTesting/unitTestingTagLibraries.adoc[leveloffset=+3]
 
 [[unitTestingDomains]]
 ==== Unit Testing Domains
@@ -1076,9 +1072,7 @@ include::security/securityPlugins/shiro.adoc[]
 include::plugins.adoc[]
 
 [[creatingAndInstallingPlugins]]
-=== Creating and Installing Plugins
-
-include::plugins/creatingAndInstallingPlugins.adoc[]
+include::plugins/creatingAndInstallingPlugins.adoc[leveloffset=+2]
 
 [[repositories]]
 === Plugin Repositories
@@ -1201,14 +1195,10 @@ include::scaffolding.adoc[]
 include::deployment.adoc[]
 
 [[deploymentStandalone]]
-=== Standalone
-
-include::deployment/deploymentStandalone.adoc[]
+include::deployment/deploymentStandalone.adoc[leveloffset=+2]
 
 [[deploymentContainer]]
-=== Container Deployment (e.g. Tomcat)
-
-include::deployment/deploymentContainer.adoc[]
+include::deployment/deploymentContainer.adoc[leveloffset=+2]
 
 [[deploymentTasks]]
 === Deployment Configuration Tasks

diff --git a/grails-doc/src/en/guide/introduction/whatsNew.adoc b/grails-doc/src/en/guide/introduction/whatsNew.adoc
@@ -19,20 +19,20 @@ under the License.
 
 This section covers all the new features introduced in Grails 7
 
-=== Overview
+==== Overview
 
 Grails 7 is a major release that includes new features, improvements, and dependency upgrades.
 This release focuses on enhancing the developer experience, improving performance, and ensuring compatibility with the latest technologies.
 
 For detailed information on how to upgrade to Grails 7, including major dependency changes, please see the xref:upgrading#upgrading60x[Upgrading from Grails 6 to Grails 7] section.
 Notable new features are included below.
 
-=== External Configuration
+==== External Configuration
 
 The https://github.com/sbglasius/external-config[external configuration plugin] is now integrated into Grails.
 See the xref:conf.adoc#externalConfiguration[Configuration] section for details.
 
-=== Ubiquitous Containerized Browser Testing with Geb
+==== Ubiquitous Containerized Browser Testing with Geb
 
 The https://github.com/apache/grails-core/tree/HEAD/grails-geb#readme[Grails Geb Plugin] has received a significant update, introducing test fixtures that enable ubiquitous containerized browser testing.
 

diff --git a/grails-doc/src/en/guide/plugins/creatingAndInstallingPlugins.adoc b/grails-doc/src/en/guide/plugins/creatingAndInstallingPlugins.adoc
@@ -18,7 +18,9 @@ under the License.
 ////
 
 
-=== Creating Plugins
+= Creating and Installing Plugins
+
+== Creating Plugins
 
 Creating a Grails plugin is a simple matter of running one of the supported plugin generators:
 
@@ -120,7 +122,7 @@ Adds Quartz job scheduling features
     Closure doWithSpring()......
 ----
 
-==== Plugin Configuration
+=== Plugin Configuration
 
 A Grails plugin can be configured in one of the following files:
 
@@ -129,7 +131,7 @@ A Grails plugin can be configured in one of the following files:
 
 These files will be included in the plugin package while the `application.*` files are only used internally when developing the plugin. See <<excludedArtefacts>>.
 
-==== Reading configuration properties
+=== Reading configuration properties
 
 Instead of directly accessing Grails configuration as `grailsApplication.config.mail.hostName`, use a Spring Boot configuration bean (or a POJO) annotated with {springbootapi}org/springframework/boot/context/properties/ConfigurationProperties.html[ConfigurationProperties] annotation. Here is an example plugin configuration:
 
@@ -169,7 +171,7 @@ class MailService {
 
 Please read the {springBootReference}features/external-config.html[Spring Boot Externalized Configuration] section for more information.
 
-==== Installing Local Plugins
+=== Installing Local Plugins
 
 In order to install the Grails plugin to your local Maven, you could use Gradle https://docs.gradle.org/current/userguide/publishing_maven.html[Maven Publish] plugin. You may also need to configure the publishing extension as:
 
@@ -216,7 +218,7 @@ implementation "org.apache.grails:grails-quartz:0.1"
 
 NOTE: In Grails 2.x plugins were packaged as ZIP files, however from Grails 3.x+ plugins are simple JAR files that can be added to the classpath of the IDE.
 
-==== Plugins and Multi-Project Builds
+=== Plugins and Multi-Project Builds
 
 
 If you wish to setup a plugin as part of a multi project build then follow these steps.
@@ -314,7 +316,7 @@ Grails application running at http://localhost:8080 in environment: development
 
 
 [[excludedArtefacts]]
-==== Notes on excluded Artefacts
+=== Notes on excluded Artefacts
 
 
 Although the link:{commandLineRef}create-plugin.html[create-plugin] command creates certain files for you so that the plugin can be run as a Grails application, not all of these files are included when packaging a plugin. The following is a list of artefacts created, but not included by link:{commandLineRef}package-plugin.html[package-plugin]:
@@ -328,7 +330,7 @@ Although the link:{commandLineRef}create-plugin.html[create-plugin] command crea
 * Everything within `/src/test/\*\*`
 * SCM management files within `\*\*/.svn/\*\*` and `\*\*/CVS/\*\*`
 
-==== Customizing the plugin contents
+=== Customizing the plugin contents
 
 
 When developing a plugin you may create test classes and sources that are used during the development and testing of the plugin but should not be exported to the application.
@@ -352,7 +354,7 @@ jar {
 }
 ----
 
-==== Inline Plugins in Grails
+=== Inline Plugins in Grails
 
 
 In Grails 2.x it was possible to specify inline plugins in `BuildConfig`, from Grails 3.x+ this functionality has been replaced by Gradle's multi-project build feature.
@@ -387,7 +389,7 @@ NOTE: You can also declare the dependency within the `dependencies` block, howev
 
 Using this technique you have achieved the equivalent of inline plugins from Grails 2.x.
 
-==== Grails Forge Creating Plugins
+=== Grails Forge Creating Plugins
 
 
 Creating a Grails plugin is a simple matter of running the command:

diff --git a/grails-doc/src/en/guide/testing/unitTesting/unitTestingTagLibraries.adoc b/grails-doc/src/en/guide/testing/unitTesting/unitTestingTagLibraries.adoc
@@ -18,7 +18,9 @@ under the License.
 ////
 
 
-=== The Basics
+= Unit Testing Tag Libraries
+
+== The Basics
 
 Tag libraries and GSP pages can be tested with the
 `grails.testing.web.taglib.TagLibUnitTest` trait.
@@ -87,7 +89,7 @@ important that the containing String be surrounded by single quotes, not double
 quotes.  `'<demo:renderSomeNumber value="${x + y}"/>'` works.
 `"<demo:renderSomeNumber value='${x + y}'/>"` would not.
 
-=== Mocking Tag Libraries
+== Mocking Tag Libraries
 
 In order to test a tag library which invokes tags from another tag library,
 the second tag library needs to be explicitly mocked by invoking the