diff --git a/spring-shell-docs/src/main/asciidoc/introduction.adoc b/spring-shell-docs/src/main/asciidoc/introduction.adoc
index 264b6590..99a19898 100644
--- a/spring-shell-docs/src/main/asciidoc/introduction.adoc
+++ b/spring-shell-docs/src/main/asciidoc/introduction.adoc
@@ -9,6 +9,15 @@ The Spring Shell project provides the infrastructure to create such a REPL (Read
 Print Loop) application, letting you concentrate on implementing commands by using
 the familiar Spring programming model.
 
-Spring Shell includes advanced features (such as parsing, tab completion, colorization of 
+Spring Shell includes advanced features (such as parsing, tab completion, colorization of
 output, fancy ASCII-art table display, input conversion, and validation), freeing you
 to focus on core command logic.
+
+[IMPORTANT]
+====
+Spring Shell 2.1.x is a major rework to bring the codebase up to date with
+existing Spring Boot versions, adding new features and, especially,
+making it work with GraalVM which makes command-line applications much
+more relevant in a Java space. Moving to a new major version also lets
+us clean up the codebase and make some needed breaking changes.
+====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc
index d164ac81..c5b09f07 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc
@@ -1,5 +1,5 @@
 [[using-shell-basics]]
-=== Basics
+== Basics
 This section covers the basics of Spring Shell. Before going on to define actual commands and options,
 we need to go through some of the fundamental concepts of Spring Shell.
 
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-building.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-building.adoc
index b8b9715e..07779306 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-building.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-building.adoc
@@ -1,10 +1,10 @@
 [[using-shell-building]]
-=== Building
+== Building
 
 This section covers how to build a Spring Shell application.
 
 [[native]]
-==== Native Support
+=== Native Support
 
 Version 2.1.x includes experimental support for compiling Spring Shell applications
 into native applications with GraalVM and Spring Native. Because the underlying JLine
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc
index a3ebf38f..086c5bda 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc
@@ -1,4 +1,4 @@
-==== Annotation Model
+=== Annotation Model
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 When you use the standard API, methods on beans are turned into executable commands, provided that:
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc
index 9deecf1d..3bf09621 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc
@@ -1,5 +1,5 @@
 [[dynamic-command-availability]]
-==== Dynamic Command Availability
+=== Dynamic Command Availability
 
 Registered commands do not always make sense, due to the internal state of the application.
 For example, there may be a `download` command, but it only works once the user has used `connect` on a remote
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exitcode.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-exitcode.adoc
index 23f19dc2..9912ec83 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exitcode.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-exitcode.adoc
@@ -1,5 +1,5 @@
 [[dynamic-command-exitcode]]
-==== Exit Code
+=== Exit Code
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Many command line applications when applicable return an _exit code_ which running environment
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc
index e0cc65d4..1f4041af 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc
@@ -1,5 +1,5 @@
 [[organizing-commands]]
-==== Organizing Commands
+=== Organizing Commands
 
 When your shell starts to provide a lot of functionality, you may end up
 with a lot of commands, which could be confusing for your users. By typing `help`,
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-programmaticmodel.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-programmaticmodel.adoc
index 625693d4..60ef8ac8 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-programmaticmodel.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-programmaticmodel.adoc
@@ -1,4 +1,4 @@
-==== Programmatic Model
+=== Programmatic Model
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 In the programmatic model, `CommandRegistration` is defined as a `@Bean`, and it is automatically registered:
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc
index 4d226a94..3c3683ed 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc
@@ -1,4 +1,4 @@
-=== Commands
+== Commands
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 In this section, we go through an actual command registration and leave command options
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc
index 642f77ae..b2123677 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc
@@ -1,8 +1,8 @@
 [[built-in-commands]]
-==== Built-In Commands
+=== Built-In Commands
 
 [[help-command]]
-===== Help
+==== Help
 
 Running a shell application often implies that the user is in a graphically limited
 environment. Also, while we are nearly always connected in the era of mobile phones,
@@ -79,17 +79,17 @@ script: Read and execute commands from a file.
 ----
 ====
 
-===== Clear
+==== Clear
 The `clear` command does what you would expect and clears the screen, resetting the prompt
 in the top left corner.
 
-===== Exit
+==== Exit
 
 The `quit` command (also aliased as `exit`) requests the shell to quit, gracefully
 closing the Spring application context. If not overridden, a JLine `History` bean writes a history of all
 commands to disk, so that they are available again on the next launch.
 
-===== Stacktrace
+==== Stacktrace
 
 When an exception occurs inside command code, it is caught by the shell and a simple, one-line message is displayed
 so as not to overflow the user with too much information.
@@ -99,14 +99,14 @@ To this end, Spring Shell remembers the last exception that occurred, and the us
 command to print all the details on the console.
 
 [[script-command]]
-===== Script
+==== Script
 
 The `script` command accepts a local file as an argument and replays commands found there, one at a time.
 
 Reading from the file behaves exactly like inside the interactive shell, so lines starting with `//` are considered
 to be comments and are ignored, while lines ending with `\` trigger line continuation.
 
-===== History
+==== History
 
 The `history` command shows the history of commands that has been executed.
 
@@ -122,7 +122,7 @@ a placeholder (`{userconfig}`), which resolves to a common shared config directo
 
 TIP: Run the Spring Shell application to see how the sample application works as it uses these options.
 
-===== Completion
+==== Completion
 
 The `completion` command set lets you create script files that can be used
 with am OS shell implementations to provide completion. This is very useful when
@@ -130,7 +130,7 @@ working with non-interactive mode.
 
 Currently, the only implementation is for bash, which works with `bash` sub-command.
 
-===== Version
+==== Version
 
 The `version` command shows existing build and git info by integrating into
 Boot's `BuildProperties` and `GitProperties` if those exist in the shell application.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-flow.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-flow.adoc
index ebacd02a..a35e3012 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-flow.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-flow.adoc
@@ -1,5 +1,5 @@
 [[using-shell-components-flow]]
-==== Flow
+=== Flow
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 When you use <<using-shell-components-ui>> to build something that involves
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc
index 341d6403..4046895c 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc
@@ -1,5 +1,5 @@
 [[using-shell-components-ui-confirmation]]
-===== Confirmation
+==== Confirmation
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 The confirmation component asks a user for a simple confirmation. It is essentially a
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc
index e5ea9bc6..b59d9540 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc
@@ -1,5 +1,5 @@
 [[using-shell-components-ui-multiselect]]
-===== Multi Select
+==== Multi Select
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 The multi select component asks a user to select multiple items from a list.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc
index 081406e2..76cb6f23 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc
@@ -1,5 +1,5 @@
 [[using-shell-components-ui-pathinput]]
-===== Path Input
+==== Path Input
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 The path input component asks a user for a `Path` and gives additional information about a path itself.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc
index f8860f40..561f977a 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc
@@ -1,5 +1,5 @@
 [[using-shell-components-ui-render]]
-===== Component Render
+==== Component Render
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 You can implement component rendering in either of two ways: fully
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc
index 9135322d..78aba16e 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc
@@ -1,5 +1,5 @@
 [[using-shell-components-ui-singleselect]]
-===== Single Select
+==== Single Select
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 A single select component asks a user to choose one item from a list. It is similar to a simple
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc
index 37b33fe2..b88574a6 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc
@@ -1,5 +1,5 @@
 [[using-shell-components-ui-stringinput]]
-===== String Input
+==== String Input
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 The string input component asks a user for simple text input, optionally masking values
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc
index e9acccfa..5fc42440 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc
@@ -1,5 +1,5 @@
 [[using-shell-components-ui]]
-==== Flow Components
+=== Flow Components
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Starting from version 2.1.x, a new component model provides an
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc
index feb394e4..b49953eb 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc
@@ -1,5 +1,5 @@
 [[using-shell-components]]
-=== Components
+== Components
 
 Components are a set of features which are either build-in or something
 you can re-use or extend for your own needs. Components in question are
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc
index 776f1043..109774ed 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc
@@ -1,5 +1,5 @@
 [[theming]]
-==== Theming
+=== Theming
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Current terminal implementations are rich in features and can usually show
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc
index 50d63515..9aab09b8 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc
@@ -1,5 +1,5 @@
 [[using-shell-customization]]
-=== Customization
+== Customization
 
 This section describes how you can customize the shell.
 
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc
index f9aa7cc4..3b695e7f 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc
@@ -1,8 +1,8 @@
-=== Execution
+== Execution
 
 This section describes how to set up a Spring Shell to work in interactive mode.
 
-==== Interaction Mode
+=== Interaction Mode
 
 Version 2.1.x introduced built-in support to distinguish between interactive
 and non-interactive modes. This makes it easier to use the shell as a
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc
index 22b3c063..5096caca 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc
@@ -1,5 +1,5 @@
 [[using-shell-options-arity]]
-==== Arity
+=== Arity
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Sometimes, you want to have more fine control of how many parameters with an option
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc
index 2d9ad35a..7dd9358f 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc
@@ -1,5 +1,5 @@
 [[using-shell-options-default]]
-==== Default Value
+=== Default Value
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Having a default value for an option is somewhat related to
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-definition.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-definition.adoc
index 6e38a23d..538894c0 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-definition.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-definition.adoc
@@ -1,5 +1,5 @@
 [[using-shell-options-definition]]
-==== Definition
+=== Definition
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Options can be defined within a target method as annotations in a method arguments
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc
index 92d83687..3e4108ae 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc
@@ -1,5 +1,5 @@
 [[using-shell-options-label]]
-==== Label
+=== Label
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 _Option Label_ has no functional behaviour within a shell itself other than
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc
index e2022ed1..9a2230bb 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc
@@ -1,5 +1,5 @@
 [[using-shell-options-optional]]
-==== Optional Value
+=== Optional Value
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 An option is either required or not and, generally speaking, how it behavesit depends on
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc
index dd81efb5..3aa1de47 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc
@@ -1,5 +1,5 @@
 [[using-shell-options-positional]]
-==== Positional
+=== Positional
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Positional information is mostly related to a command target method:
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc
index 0f0fb1c2..79de493e 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc
@@ -1,5 +1,5 @@
 [[using-shell-options-short]]
-==== Short Format
+=== Short Format
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Short style _POSIX_ option in most is just a synonym to long format but
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc
index ea397624..9676a814 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc
@@ -1,5 +1,5 @@
 [[validating-command-arguments]]
-==== Validation
+=== Validation
 
 Spring Shell integrates with the https://beanvalidation.org/[Bean Validation API] to support
 automatic and self-documenting constraints on command parameters.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
index 85691ef6..a61ac564 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
@@ -1,5 +1,5 @@
 [[using-shell-options]]
-=== Options
+== Options
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Command line arguments can be separated into options and positional parameters.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell.adoc b/spring-shell-docs/src/main/asciidoc/using-shell.adoc
index dea58ff8..0dfe966c 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell.adoc
@@ -1,15 +1,3 @@
-== Using Spring Shell
-This section describes how to use Spring Shell.
-
-[IMPORTANT]
-====
-Spring Shell 2.1.x is a major rework to bring the codebase up to date with
-existing Spring Boot versions, adding new features and, especially,
-making it work with GraalVM which makes command-line applications much
-more relevant in a Java space. Moving to a new major version also lets
-us clean up the codebase and make some needed breaking changes.
-====
-
 include::using-shell-basics.adoc[]
 
 include::using-shell-commands.adoc[]