Documentation: Cleanup Title Sequence

[jamesfredley]

Issue description

Run ./gradlew assemble

Review and correct error like the following:

WARNING: eventsAutoTimestamping.adoc: line 36: section title out of sequence: expected level 1, got level 3
WARNING: eventsAutoTimestamping.adoc: line 174: section title out of sequence: expected level 1, got level 3
WARNING: eventsAutoTimestamping.adoc: line 91: section title out of sequence: expected level 1, got level 3
WARNING: eventsAutoTimestamping.adoc: line 114: section title out of sequence: expected level 1, got level 3
WARNING: configurationDefaults.adoc: line 22: section title out of sequence: expected level 1, got level 3

[dauer]

The issue is that the documentation is assembled from multiple documents.

The root document index.adoc includes multiple other documents fx. advancedGORMFeatures/eventsAutoTimestamping.adoc When the included documents are processed individually Asciidoctor complains about the headlines starting from level 3 (which is where the root document expects them).

Solution 1 I think a solution is to write the documents as if they where not to be inserted in the root document (treat them as individual docs), meaning headlines starts from level 1. When inserted into the root document (index.adoc) we then adjust the level offset: include::advancedGORMFeatures/eventsAutoTimestamping.adoc[leveloffset=+2]

https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/

The drawback is that it requires some editing, there are a lot of *.adoc files...

Solution 2 Or if we don't want to generate the files in the sub folders, prefix those documents and folders with an underscore _ which will exclude them unless they are included from other files.

[jamesfredley]

Solution 1 is the selected direction

[jamesfredley]

Here is a current example of a slightly different take on Solution 1.

https://github.com/apache/grails-core/blob/0c944d3556b3fdffb4f81a15fdd390b4e58ee6a4/grails-doc/src/en/guide/index.adoc?plain=1#L268-L277

https://github.com/apache/grails-core/blob/1d49052586a2246acf9772cff45009332022c0b2/grails-doc/src/en/guide/profiles/creatingProfiles.adoc?plain=1#L19-L53