diff --git a/docs/src/main/asciidoc/config-yaml.adoc b/docs/src/main/asciidoc/config-yaml.adoc
deleted file mode 100644
index 33109f1b38aaaa..00000000000000
--- a/docs/src/main/asciidoc/config-yaml.adoc
+++ /dev/null
@@ -1,209 +0,0 @@
-////
-This guide is maintained in the main Quarkus repository
-and pull requests should be submitted there:
-https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
-////
-= YAML Configuration
-include::_attributes.adoc[]
-:categories: core
-:summary: YAML as a Configuration Source.
-
-https://en.wikipedia.org/wiki/YAML[YAML] is a very popular format. Kubernetes relies heavily on the YAML format to
-write the various resource descriptors.
-
-Quarkus offers the possibility to use YAML in addition to the standard Java Properties file.
-
-== Enabling YAML Configuration
-
-To enable YAML configuration, add the `quarkus-config-yaml` extension:
-
-:add-extension-extensions: quarkus-config-yaml
-include::{includes}/devtools/extension-add.adoc[]
-
-You can also just add the following dependency into your project:
-
-[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
-.pom.xml
-----
-<dependency>
-    <groupId>io.quarkus</groupId>
-    <artifactId>quarkus-config-yaml</artifactId>
-</dependency>
-----
-
-[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
-.build.gradle
-----
-implementation("io.quarkus:quarkus-config-yaml")
-----
-
-Remove the `src/main/resources/application.properties` and create a `src/main/resources/application.yaml` file.
-
-NOTE: If both are present, Quarkus prioritizes configuration properties from the YAML file first and then from the
-Properties file. However, to avoid confusion, we recommend removing the Properties file.
-
-TIP: Quarkus supports both the  `yml` and `yaml` file extensions.
-
-=== Example
-
-The following snippets provide examples of YAML configuration:
-
-[source,yaml]
-----
-# YAML supports comments
-quarkus:
-  datasource:
-    db-kind: postgresql
-    jdbc:
-      url: jdbc:postgresql://localhost:5432/some-database
-
-# REST Client configuration property
-quarkus:
-  rest-client:
-    org.acme.rest.client.ExtensionsService:
-      url: https://stage.code.quarkus.io/api
-----
-
-[source,yaml]
-----
-# For configuration property names that use quotes, do not split the string inside the quotes
-quarkus:
-  log:
-    category:
-      "io.quarkus.category":
-        level: INFO
-----
-
-[source, yaml]
-----
-quarkus:
-  datasource:
-    url: jdbc:postgresql://localhost:5432/quarkus_test
-
-  hibernate-orm:
-    database:
-      generation: drop-and-create
-
-  oidc:
-    enabled: true
-    auth-server-url: http://localhost:8180/auth/realms/quarkus
-    client-id: app
-
-
-app:
-  frontend:
-    oidc-realm: quarkus
-    oidc-app: app
-    oidc-server: http://localhost:8180/auth
-
-# With profiles
-"%test":
-   quarkus:
-     oidc:
-       enabled: false
-     security:
-        users:
-            file:
-              enabled: true
-              realm-name: quarkus
-              plain-text: true
-----
-
-== Profiles
-
-As you can see in the previous snippet, you can use xref:config-reference.adoc#profiles[profiles] in YAML. The profile
-key requires double quotes: `"%test"`. This is because YAML does not support keys starting with `%`.
-
-Everything under the `"%test"` key is only enabled when the `test` profile is active. For example, in the previous
-snippet it disables OIDC (`quarkus.oidc.enabled: false`), whereas without the `test` profile, it would be enabled.
-
-As for the Java Properties format, you can define your own profile:
-
-[source, yaml]
-----
-quarkus:
-  http:
-    port: 8081
-
-"%staging":
-    quarkus:
-        http:
-          port: 8082
-----
-
-If you enable the `staging` profile, the HTTP port will be 8082, whereas it would be 8081 otherwise.
-
-The YAML configuration also support profile aware files. In this case, properties for a specific profile may reside in
-an `application-{profile}.yaml` named file. The previous example may be expressed as:
-
-.application.yaml
-[source, yaml]
-----
-quarkus:
-  http:
-    port: 8081
-----
-
-.application-staging.yaml
-[source, yaml]
-----
-quarkus:
-  http:
-    port: 8082
-----
-
-== Expressions
-
-The YAML format also supports xref:config-reference.adoc#property-expressions[property expressions], using the same format as Java
-Properties:
-
-[source, yaml]
-----
-mach: 3
-x:
-  factor: 2.23694
-
-display:
-  mach: ${mach}
-  unit:
-    name: "mph"
-    factor: ${x.factor}
-----
-
-Note that you can reference nested properties using the `.` (dot) separator as in `${x.factor}`.
-
-== External application.yaml file
-
-The `application.yaml` file may also be placed in `config/application.yaml` to specialize the runtime configuration. The
-file has to be present in the root of the working directory relative to the Quarkus application runner:
-
-[source, text]
-----
-.
-├── config
-│    └── application.yaml
-├── my-app-runner
-----
-
-The values from this file override any values from the regular `application.yaml` file if exists.
-
-== Configuration key conflicts
-
-The MicroProfile Config specification defines configuration keys as an arbitrary `.`-delimited string. However,
-structured formats like YAML only support a subset of the possible configuration namespace. For example, consider the
-two configuration properties `quarkus.http.cors` and `quarkus.http.cors.methods`. One property is the prefix of another,
-so it may not be immediately evident how to specify both keys in your YAML configuration.
-
-This is solved by using a `null` key (represented by `~`) for any YAML property which is a prefix of another one:
-
-[source,yaml]
-----
-quarkus:
-  http:
-    cors:
-      ~: true
-      methods: GET,PUT,POST
-----
-
-YAML `null` keys are not included in the assembly of the configuration property name, allowing them to be used
-in any level for disambiguating configuration keys.
diff --git a/docs/src/main/asciidoc/config-your-quarkus-applications-using-a-yaml-file_howto.adoc b/docs/src/main/asciidoc/config-your-quarkus-applications-using-a-yaml-file_howto.adoc
new file mode 100644
index 00000000000000..e24e4b4cf0e973
--- /dev/null
+++ b/docs/src/main/asciidoc/config-your-quarkus-applications-using-a-yaml-file_howto.adoc
@@ -0,0 +1,407 @@
+////
+This document is maintained in the main Quarkus repository, and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+[id="configure-a-yaml-application-properties-file"]
+= Configure a YAML application properties file
+include::_attributes.adoc[]
+:categories: core
+:summary: Use `application.yaml` instead of `application.properties`.
+
+Optionally, you can use a YAML-formatted file, `application.yaml`, instead of the default `application.properties` file to configure your application.
+
+link:https://en.wikipedia.org/wiki/YAML[YAML] is a popular format.
+For example, Kubernetes relies on YAML to write various resource descriptors.
+
+.Prerequisites
+
+* You have installed JDK 11 or later and set the `JAVA_HOME` environment variable to specify the location of the Java SDK.
+
+* You have installed Apache Maven {maven-version}.
+
+// include::modules/con_overview-quarkus-configuration.adoc[leveloffset=+1]
+[id="con_overview-quarkus-configuration"]
+== Overview
+
+Configuration options enable you to change the settings of your application in a single configuration file.
+
+{project-name} supports configuration profiles that you can use to group related properties and switch between profiles as required.
+
+By default, {project-name} reads properties from the `application.properties` file located in the `src/main/resources` directory.
+Instead, you can configure {project-name} to read properties from a YAML file.
+
+When you add the `quarkus-config-yaml` dependency to your project `pom.xml` file, you can configure and manage your application properties in the `application.yaml` file.
+
+For more information, see the xref:proc_enabling_yaml_configuration[Enabling YAML configuration].
+
+{project-name} supports YAML configuration files through the `SmallRye Config` implementation of Eclipse MicroProfile Config.
+
+You can use the link:https://microprofile.io/project/eclipse/microprofile-config[MicroProfile Config] specification from the Eclipse MicroProfile project to inject configuration properties into your application and access them using a method defined in your code.
+
+{project-name} can also read application properties from different origins, including the following sources:
+
+* The file system
+* A database
+* A Kubernetes or OpenShift `ConfigMap` or Secret object
+* Any source that a Java application can load
+
+// WAS include::modules/proc_adding-yaml-configuration-support.adoc[leveloffset=+1]
+// include::modules/proc_enabling_yaml_configuration.adoc[leveloffset=+1]
+[id="proc_enabling_yaml_configuration"]
+== Enabling YAML configuration
+
+To enable YAML configuration, add the `quarkus-config-yaml` extension:
+
+:add-extension-extensions: quarkus-config-yaml
+include::{includes}/devtools/extension-add.adoc[]
+
+You can also just add the following dependency into your project:
+
+[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
+.pom.xml
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-config-yaml</artifactId>
+</dependency>
+----
+
+[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
+.build.gradle
+----
+implementation("io.quarkus:quarkus-config-yaml")
+----
+
+Remove the `src/main/resources/application.properties` and create a `src/main/resources/application.yaml` file.
+
+NOTE: If both are present, Quarkus prioritizes configuration properties from the YAML file first and then from the
+Properties file. However, to avoid confusion, we recommend removing the Properties file.
+
+TIP: Quarkus supports both the  `yml` and `yaml` file extensions.
+
+// include::modules/proc_using-nested-object-configuration-with-yaml.adoc[leveloffset=+2]
+
+[id="proc_using-nested-object-configuration-with-yaml"]
+
+== Using nested object configuration with YAML
+
+In a YAML configuration file, you can define a nested class inside an existing class to set configuration properties for your {project-name} application.
+
+.Prerequisites
+
+* You have a {project-name} Maven project.
+* You have a PostgreSQL data source.
+* You have the following extensions as dependencies in the `pom.xml` file of your project:
+** `quarkus-rest-client`
+** `quarkus-jdbc-postgresql`
+** `quarkus-config-yaml`
+
+.Procedure
+
+. Open the `src/main/resources/application.yaml` configuration file.
+
+. Add the nested class configuration properties to your `application.yaml` file, as shown in the following example:
++
+.Example `application.yaml` file
+[source,yaml]
+----
+# Properties that configure the JDBC data source driver of your PostgreSQL data source
+quarkus:
+  datasource:
+    url: jdbc:postgresql://localhost:5432/some-database
+    driver: org.postgresql.Driver
+    username: quarkus
+    password: quarkus
+
+# Property that configures the URL of the endpoint to which the rest client sends requests
+org:
+  acme:
+    restclient:
+      CountriesService/mp-rest/url: https://restcountries.eu/rest
+
+# Property that configures the log message level for your application
+quarkus:
+  log:
+    category:
+
+# Do not use spaces in names of configuration properties that you place inside quotation marks
+      "io.quarkus.category":
+        level: INFO
+----
++
+Similarly to using the comments in the `application.properties` file, you can use comments to describe your configuration properties in YAML format.
++
+[NOTE]
+====
+Always use spaces to indent the properties in your YAML configuration file.
+YAML does not support using tabs for indentation.
+====
+
+// CREATE include::modules/conc_configuration-profiles-with-yaml.adoc[leveloffset=+2]
+[id="conc_configuration-profiles-with-yaml"]
+== Configuration profiles with YAML
+
+You can use xref:config-reference.adoc#profiles[profiles] in YAML.
+
+Because YAML does not support names that start with `%`, you must enclose the names of configuration keys between double quotes.
+
+For example, in `application.yaml`, you must use `"%dev"` or `"%test"` as the configuration keys to identify properties that you want to your Quarkus project to use when you build and run it using using the development or test profiles.
+
+.Example `application.yaml` with production and development profiles
+[source, yaml]
+----
+quarkus:
+  http:
+    port: 8081
+
+"%dev":
+    quarkus:
+        http:
+          port: 8082
+----
+
+Quarkus runs the production profile by default. With the preceding example, if you don't specify a profile, the HTTP port number is `8081`. If you enable the development profile, the HTTP port number is `8082`.
+
+The YAML configuration also supports profile-aware files. In this case, properties for a specific profile may reside in
+an `application-{profile}.yaml` named file. The previous example may be expressed as:
+
+.application.yaml
+[source, yaml]
+----
+quarkus:
+  http:
+    port: 8081
+----
+
+.application-development.yaml
+[source, yaml]
+----
+quarkus:
+  http:
+    port: 8082
+----
+
+// include::modules/proc_setting-custom-configuration-profiles-with-yaml.adoc[leveloffset=+2]
+[id="proc_setting-custom-configuration-profiles-with-yaml"]
+== Setting custom configuration profiles with YAML
+
+With {project-name}, you can set configuration properties and values specific to your application's different configuration profiles.
+You can start your application with a specific profile to access a particular configuration.
+This procedure shows how you can configure a specific profile in YAML format.
+
+.Prerequisites
+
+* You have a {project-name} Maven project configured to use a PostgreSQL data source with a JDBC data source driver.
+* You have the `quarkus-jdbc-postgresql` and `quarkus-config-yaml` extensions as dependencies in your project's `pom.xml` file.
+
+.Procedure
+
+. Open the `src/main/resources/application.yaml` configuration file.
+
+. To set a profile-dependent configuration, add the profile name before defining the key-value pairs by using the `"%<profile_name>"` syntax.
+Ensure that you place the profile name inside quotation marks.
++
+[TIP]
+====
+In YAML, you must place all strings that begin with a special character inside quotation marks.
+====
++
+In the following example, the PostgreSQL database is configured to be available at the `jdbc:postgresql://localhost:5432/some-database` URL when you start your {project-name} application in development mode:
++
+.src/main/resources/application.yaml
+[source,yaml]
+----
+"%dev":
+  # Properties that configure the JDBC data source driver of your PostgreSQL data source
+  quarkus:
+    datasource:
+      url: jdbc:postgresql://localhost:5432/some-database
+      driver: org.postgresql.Driver
+      username: quarkus
+      password: quarkus
+----
+
+// include::modules/con_property-expressions.adoc[leveloffset=+1]
+[id="con_property-expressions"]
+== Property expressions
+
+Property expressions are combinations of property references and plain text strings that you can use to substitute values of properties in your configuration.
+
+Much like a variable, you can use a property expression in {project-name} to substitute a configuration property value instead of hardcoding it.
+A property expression is resolved when `java.util.Properties` reads the property's value from a configuration source in your application.
+
+If a configuration property is read from your configuration at compile time, the property expression is also resolved at compile time.
+If the configuration property is overridden at runtime, its value is resolved at runtime.
+
+You can resolve property expressions by using more than one configuration source.
+This means that you can use the value of a property in one configuration source to expand a property expression that you use in another.
+
+If the value of a property in an expression cannot be resolved, and you do not set a default value for the expression, your application encounters a `NoSuchElementException`.
+
+//Property expressions use the `${<property_name>}` syntax.
+
+// include::modules/ref_example-usage-of-property-expressions-using-a-yaml-file.adoc[leveloffset=+2]
+
+[id="ref_example-usage-of-property-expressions-using-a-yaml-file"]
+== Example usage of property expressions using a YAML file
+
+This section shows examples of using property expressions to achieve flexibility when configuring your {project-name} application.
+
+.Example `application.yaml` file
+[source,properties,options="nowrap"]
+----
+mach: 3
+x:
+  factor: 2.23694
+
+display:
+  mach: ${mach}
+  unit:
+    name: "mph"
+    factor: ${x.factor}
+----
+
+[NOTE]
+====
+You can reference nested properties by using the `.` (dot) separator, as in `{x.factor}`.
+====
+
+.Additional resources
+
+* For more information about property expressions, see xref:con_property-expressions[Property expressions].
+// * For an example of property expressions using a properties file, see link:{URL_CONFIGURATION_QUARKUS}#ref_example-usage-of-property-expressions_quarkus-configuration-guide[Example usage of property expressions]. // TBD update and enable this ^ link later when this guide becomes available
+
+// include::modules/con_external-application-yaml-file-for-configuring-properties-at-runtime.adoc[leveloffset=+1]
+[id="con_external-application-yaml-file-for-configuring-properties-at-runtime"]
+== External application.yaml file for configuring properties at runtime
+
+To configure your application properties at runtime, add your `application.yaml` file to the `config` directory.
+[NOTE]
+====
+If one exists, the values in the `config/application.yaml` file override any values from the regular `application.yaml` file.
+====
+Ensure that the `config/application.yaml` file is in the root of the working directory relative to the {project-name} application runner, as outlined in the following example:
+
+[source,properties,options="nowrap"]
+----
+├── config
+│    └── application.yaml
+├── my-app-runner
+----
+
+.Additional resources
+
+* xref:proc_enabling_yaml_configuration[Enabling YAML configuration].
+
+//include::modules/proc_managing-configuration-key-conflicts.adoc[leveloffset=+1]
+
+[id="proc_managing-configuration-key-conflicts"]
+
+== Managing configuration key conflicts
+
+Structured formats such as YAML only support a subset of the possible configuration namespace.
+The following procedure shows how to resolve a conflict between two configuration properties, `quarkus.http.cors` and `quarkus.http.cors.methods`, where one property is the prefix of another.
+
+.Prerequisites
+
+* You have a {project-name} project configured to read YAML configuration files.
+
+.Procedure
+
+. Open your YAML configuration file.
+
+. To define a YAML property as a prefix of another property, add a tilde (`~`) in the scope of the property as shown in the following example:
++
+.Example of defining a YAML property as a prefix
+[source,yaml]
+----
+quarkus:
+  http:
+    cors:
+      ~: true
+      methods: GET,PUT,POST
+----
++
+. To compile your {project-name} application in development mode, enter the following command from the project directory:
++
+.Compile your {project-name} application
+[source,bash]
+----
+./mvnw quarkus:dev
+----
++
+[NOTE]
+====
+You can use YAML keys for conflicting configuration keys at any level because they are not included in the assembly of the configuration property name.
+====
+
+// == Additional resources
+//
+// * link:{URL_CONFIGURATION_QUARKUS}[Configuring your {project-name} applications by using a properties file]  // TBD update link
+// TBD update and enable this ^ link later when this guide becomes available
+
+
+=== Other example configurations
+
+The following snippets provide examples of YAML configuration:
+
+[source,yaml]
+----
+# YAML supports comments
+quarkus:
+  datasource:
+    db-kind: postgresql
+    jdbc:
+      url: jdbc:postgresql://localhost:5432/some-database
+
+# REST Client configuration property
+quarkus:
+  rest-client:
+    org.acme.rest.client.ExtensionsService:
+      url: https://stage.code.quarkus.io/api
+----
+
+[source,yaml]
+----
+# For configuration property names that use quotes, do not split the string inside the quotes
+quarkus:
+  log:
+    category:
+      "io.quarkus.category":
+        level: INFO
+----
+
+[source, yaml]
+----
+quarkus:
+  datasource:
+    url: jdbc:postgresql://localhost:5432/quarkus_test
+
+  hibernate-orm:
+    database:
+      generation: drop-and-create
+
+  oidc:
+    enabled: true
+    auth-server-url: http://localhost:8180/auth/realms/quarkus
+    client-id: app
+
+
+app:
+  frontend:
+    oidc-realm: quarkus
+    oidc-app: app
+    oidc-server: http://localhost:8180/auth
+
+# With profiles
+"%test":
+   quarkus:
+     oidc:
+       enabled: false
+     security:
+        users:
+            file:
+              enabled: true
+              realm-name: quarkus
+              plain-text: true
+----