Configuration asciidoc macro migration

src/main/docs/guide/cloud/cloudConfiguration/distributedConfigurationAwsParameterStore.adoc

@@ -4,7 +4,6 @@ dependency:io.micronaut.aws:micronaut-aws-parameter-store[]
 
 To enable distributed configuration, make sure <<bootstrap>> is enabled and create a `src/main/resources/bootstrap.yml` file with the following configuration:
 
-.bootstrap.yml
 [configuration]
 ----
 micronaut:

src/main/docs/guide/cloud/cloudConfiguration/distributedConfigurationConsul.adoc

@@ -25,7 +25,6 @@ $ mn create-app my-app --features config-consul
 
 To enable distributed configuration make sure <<bootstrap>> is enabled and create a `src/main/resources/bootstrap.[yml/toml/properties]` file with the following configuration:
 
-.bootstrap configuration
 [configuration]
 ----
 micronaut:

src/main/docs/guide/cloud/cloudConfiguration/distributedConfigurationSpringCloud.adoc

@@ -15,10 +15,13 @@ spring:
     config:
       enabled: true
       uri: http://localhost:8888/
-      retry-attempts: 4 # optional, number of times to retry
-      retry-delay: 2s # optional, delay between retries
+      retry-attempts: 4
+      retry-delay: 2s
 ----
 
+- `retry-attempts` is optional, and specifies the number of times to retry
+- `retry-delay` is optional, and specifies the delay between retries
+
 Micronaut uses the configured `micronaut.application.name` to look up property sources for the application from Spring Cloud config server configured via `spring.cloud.config.uri`.
 
 See the https://spring.io/projects/spring-cloud-config#learn[Documentation for Spring Cloud Config Server] for more information on how to set up the server.

src/main/docs/guide/cloud/serviceDiscovery/serviceDiscoveryManual.adoc

@@ -29,13 +29,13 @@ micronaut:
   http:
     services:
       foo:
-        health-check: true # <1>
-        health-check-interval: 15s # <2>
-        health-check-uri: /health # <3>
+        health-check: true
+        health-check-interval: 15s
+        health-check-uri: /health
 ----
 
-<1> Whether to health check the service
-<2> The interval between checks
-<3> The URI of the health check request
+- `health-check` indicates whether to health check the service
+- `health-check-interval` is the interval between checks
+- `health-check-uri` specifies the endpoint URI of the health check request
 
 Micronaut starts a background thread to check the health status of the service and if any of the configured services respond with an error code, they are removed from the list of available services.

src/main/docs/guide/cloud/serviceDiscovery/serviceDiscoveryRoute53.adoc

@@ -13,7 +13,7 @@ Here are the steps:
 3. Add health checks or custom health checks (optional)
 4. Add Service ID to your application configuration file like so:
 
-.Sample application.yml
+.Sample application configuration
 [configuration]
 ----
 aws:
@@ -33,7 +33,6 @@ dependency:io.micronaut.aws:micronaut-aws-route53[]
 
 6. On the client side, you need the same dependencies and fewer configuration options:
 
-.Sample application.yml
 [configuration]
 ----
 aws:

src/main/docs/guide/config/valueAnnotation.adoc

@@ -91,7 +91,6 @@ The above instead injects the value of the `my.url` property resolved from appli
 
 You can also use this feature to resolve sub maps. For example, consider the following configuration:
 
-.Example `application.yml` configuration
 [configuration]
 ----
 datasources:

src/main/docs/guide/httpClient/clientAnnotation/clientHeaders.adoc

@@ -12,7 +12,7 @@ The above example defines a ann:http.annotation.Header[] annotation on the `PetC
 
 Then set the following in your configuration file (e.g `application.yml`) to populate the value:
 
-.Configuring Headers in YAML
+.Configuring Headers
 [configuration]
 ----
 pet:

src/main/docs/guide/httpClient/lowLevelHttpClient/clientConfiguration.adoc

@@ -27,10 +27,10 @@ micronaut:
         urls:
           - http://foo1
           - http://foo2
-        read-timeout: 5s # <1>
+        read-timeout: 5s
 ----
 
-<1> The read timeout is applied to the `foo` client.
+- The `read-timeout` is applied to the `foo` client.
 
 WARN: This client configuration can be used in conjunction with the `@Client` annotation, either by injecting an `HttpClient` directly or use on a client interface. In any case, all other attributes on the annotation *will be ignored* except the service id.
 
@@ -98,10 +98,10 @@ micronaut:
           - http://foo1
           - http://foo2
         pool:
-          max-concurrent-http1-connections: 50 # <1>
+          max-concurrent-http1-connections: 50
 ----
 
-<1> Limit maximum concurrent HTTP/1.1 connections
+- Limit maximum concurrent HTTP/1.1 connections
 
 See the API for link:{api}/io/micronaut/http/client/HttpClientConfiguration.ConnectionPoolConfiguration.html[ConnectionPoolConfiguration] for details on available pool configuration options.
 

src/main/docs/guide/httpServer/apiVersioning.adoc

@@ -26,22 +26,22 @@ By default Micronaut has two strategies for resolving the version based on an HT
 micronaut:
   router:
     versioning:
-      enabled: true <1>
+      enabled: true
       parameter:
-        enabled: false # <2>
-        names: 'v,api-version' # <3>
+        enabled: false
+        names: 'v,api-version'
       header:
-        enabled: true # <4>
-        names: # <5>
+        enabled: true
+        names:
           - 'X-API-VERSION'
           - 'Accept-Version'
 ----
 
-<1> Enables versioning
-<2> Enables or disables parameter-based versioning
-<3> Specify the parameter names as a comma-separated list
-<4> Enables or disables header-based versioning
-<5> Specify the header names as a list
+- This example enables versioning
+- `parameter.enabled` enables or disables parameter-based versioning
+- `parameter.names` specifies the parameter names as a comma-separated list
+- `header.enabled` enables or disables header-based versioning
+- `header.names` specifies the header names as a list
 
 If this is not enough you can also implement the api:web.router.version.resolution.RequestVersionResolver[] interface which receives the api:http.HttpRequest[] and can implement any strategy you choose.
 
@@ -56,10 +56,10 @@ micronaut:
   router:
     versioning:
       enabled: true
-      default-version: 3 <1>
+      default-version: 3
 ----
 
-<1> Sets the default version
+- This example enables versioning and sets the default version
 
 A route is *not* matched if the following conditions are met:
 

src/main/docs/guide/httpServer/runningSpecificPort.adoc

@@ -1,6 +1,6 @@
 By default the server runs on port 8080. However, you can set the server to run on a specific port:
 
-[source, yaml]
+[configuration]
 ----
 micronaut:
   server:
@@ -11,7 +11,7 @@ TIP: This is also configurable from an environment variable, e.g. `MICRONAUT_SER
 
 To run on a random port:
 
-[source, yaml]
+[configuration]
 ----
 micronaut:
   server:

src/main/docs/guide/httpServer/serverConfiguration.adoc

@@ -8,18 +8,18 @@ The following example shows how to tweak configuration options for the server vi
 micronaut:
   server:
     maxRequestSize: 1MB
-    host: localhost # <1>
+    host: localhost
     netty:
-      maxHeaderSize: 500KB # <2>
+      maxHeaderSize: 500KB
       worker:
-        threads: 8 # <3>
+        threads: 8
       childOptions:
-        autoRead: true # <4>
+        autoRead: true
 ----
-<1> By default Micronaut binds to all network interfaces. Use `localhost` to bind only to loopback network interface
-<2> Maximum size for headers
-<3> Number of Netty worker threads
-<4> Auto read request body
+- By default Micronaut binds to all network interfaces. Use `localhost` to bind only to loopback network interface
+- `maxHeaderSize` sets the maximum size for headers
+- `worker.threads` specifies the number of Netty worker threads
+- `autoRead` enables request body auto read
 
 include::{includedir}configurationProperties/io.micronaut.http.server.netty.configuration.NettyHttpServerConfiguration.adoc[]
 

src/main/docs/guide/httpServer/serverConfiguration/accessLogger.adoc

@@ -9,11 +9,15 @@ micronaut:
   server:
     netty:
       access-logger:
-        enabled: true # Enables the access logger
-        logger-name: my-access-logger # A logger name, optional, default is `HTTP_ACCESS_LOGGER`
-        log-format: common # A log format, optional, default is Common Log Format
+        enabled: true
+        logger-name: my-access-logger
+        log-format: common
 ----
 
+- `enabled` Enables the access logger
+- optionally specify a `logger-name`, which defaults to `HTTP_ACCESS_LOGGER`
+- optionally specify a `log-format`, which defaults to the Common Log Format
+
 ==== Filtering access logs
 
 If you wish to not log access to certain paths, you can specify regular expression filters in the configuration:
@@ -25,14 +29,18 @@ micronaut:
   server:
     netty:
       access-logger:
-        enabled: true # Enables the access logger
-        logger-name: my-access-logger # A logger name, optional, default is `HTTP_ACCESS_LOGGER`
-        log-format: common # A log format, optional, default is Common Log Format
+        enabled: true
+        logger-name: my-access-logger
+        log-format: common
         exclusions:
           - /health
           - /path/.+
 ----
 
+- `enabled` Enables the access logger
+- optionally specify a `logger-name`, which defaults to `HTTP_ACCESS_LOGGER`
+- optionally specify a `log-format`, which defaults to the Common Log Format
+
 ==== Logback Configuration
 
 In addition to enabling the access logger, you must add a logger for the specified or default logger name. For instance using the default logger name for logback:

src/main/docs/guide/httpServer/serverConfiguration/cors/corsAllowCredentials.adoc

@@ -1,7 +1,7 @@
 Credentials are allowed by default for CORS requests. To disallow credentials, set the `allowCredentials` option to `false`.
 
 .Example CORS Configuration
-[source,yaml]
+[configuration]
 ----
 micronaut:
   server:

src/main/docs/guide/httpServer/serverConfiguration/cors/corsAllowedHeaders.adoc

@@ -3,7 +3,7 @@ To allow any request header for a given configuration, don't include the `allowe
 For multiple allowed headers, set the `allowedHeaders` key of the configuration to a list of strings.
 
 .Example CORS Configuration
-[source,yaml]
+[configuration]
 ----
 micronaut:
   server:

src/main/docs/guide/httpServer/serverConfiguration/cors/corsAllowedMethods.adoc

@@ -3,7 +3,7 @@ To allow any request method for a given configuration, don't include the `allowe
 For multiple allowed methods, set the `allowedMethods` key of the configuration to a list of strings.
 
 .Example CORS Configuration
-[source,yaml]
+[configuration]
 ----
 micronaut:
   server:

src/main/docs/guide/httpServer/serverConfiguration/cors/corsAllowedOrigins.adoc

@@ -5,7 +5,7 @@ For multiple valid origins, set the `allowedOrigins` key of the configuration to
 Regular expressions are passed to link:{javase}java/util/regex/Pattern.html#compile-java.lang.String-[Pattern#compile] and compared to the request origin with link:{javase}java/util/regex/Matcher.html#matches--[Matcher#matches].
 
 .Example CORS Configuration
-[source,yaml]
+[configuration]
 ----
 micronaut:
   server:

src/main/docs/guide/httpServer/serverConfiguration/cors/corsConfiguration.adoc

@@ -1,7 +1,7 @@
 To enable processing of CORS requests, modify your configuration. For example with `application.yml`:
 
 .CORS Configuration Example
-[source,yaml]
+[configuration]
 ----
 micronaut:
   server:
@@ -14,7 +14,7 @@ By only enabling CORS processing, a "wide open" strategy is adopted that allows
 To change the settings for all origins or a specific origin, change the configuration to provide one or more "configurations". By providing any configuration, the default "wide open" configuration is not configured.
 
 .CORS Configurations
-[source,yaml]
+[configuration]
 ----
 micronaut:
   server:

src/main/docs/guide/httpServer/serverConfiguration/cors/corsExposedHeaders.adoc

@@ -1,7 +1,7 @@
 To configure the headers that are sent in the response to a CORS request through the `Access-Control-Expose-Headers` header, include a list of strings for the `exposedHeaders` key in your configuration. None are exposed by default.
 
 .Example CORS Configuration
-[source,yaml]
+[configuration]
 ----
 micronaut:
   server:

src/main/docs/guide/httpServer/serverConfiguration/cors/corsMaxAge.adoc

@@ -1,7 +1,7 @@
 The default maximum age that preflight requests can be cached is 30 minutes. To change that behavior, specify a value in seconds.
 
 .Example CORS Configuration
-[source,yaml]
+[configuration]
 ----
 micronaut:
   server:

src/main/docs/guide/httpServer/serverConfiguration/cors/corsMultipleHeaderValues.adoc

@@ -1,6 +1,6 @@
 By default, when a header has multiple values, multiple headers are sent, each with a single value. It is possible to change the behavior to send a single header with a comma-separated list of values by setting a configuration option.
 
-[source,yaml]
+[configuration]
 ----
 micronaut:
   server:

src/main/docs/guide/httpServer/serverConfiguration/dualProtocol.adoc

@@ -7,11 +7,11 @@ micronaut:
   server:
     ssl:
       enabled: true
-      build-self-signed: true # <1>
-    dual-protocol : true #<2>
+      build-self-signed: true
+    dual-protocol : true
 ----
-<1> You must configure SSL for HTTPS to work. In this example we are just using a self-signed certificate, but see <<https, Securing the Server with HTTPS>> for other configurations
-<2> Enabling both HTTP and HTTPS is an opt-in feature - setting the `dualProtocol` flag enables it. By default Micronaut only enables one
+- You must configure SSL for HTTPS to work. In this example we are just using a self-signed certificate with `build-self-signed`, but see <<https, Securing the Server with HTTPS>> for other configurations
+- `dual-protocol` enables both HTTP and HTTPS is an opt-in feature - setting the `dualProtocol` flag enables it. By default Micronaut only enables one
 
 
 It is also possible to redirect automatically all HTTP request to HTTPS. Besides the previous configuration, you need to enable this option. For example:
@@ -25,6 +25,7 @@ micronaut:
       enabled: true
       build-self-signed: true
     dual-protocol : true
-    http-to-https-redirect: true # <1>
+    http-to-https-redirect: true
 ----
-<1> Enable HTTP to HTTPS redirects
+
+- `http-to-https-redirect` enables HTTP to HTTPS redirects

src/main/docs/guide/httpServer/serverConfiguration/https.adoc

@@ -7,11 +7,11 @@ micronaut:
   server:
     ssl:
       enabled: true
-      buildSelfSigned: true # <1>
+      buildSelfSigned: true
 ----
-<1> Micronaut will create a self-signed certificate.
+- Micronaut will create a self-signed certificate.
 
-TIP: By default Micronaut with HTTPS support starts on port `8443` but you can change the port with the property `micronaut.server.ssl.port`.
+TIP: By default, Micronaut with HTTPS support starts on port `8443` but you can change the port with the property `micronaut.server.ssl.port`.
 
 For generating self-signed certificates, the Micronaut HTTP server will use netty. Netty uses one of two approaches to generate the certificate.
 
@@ -55,12 +55,12 @@ micronaut:
   ssl:
     enabled: true
     key-store:
-      path: classpath:server.p12 # <1>
-      password: mypassword # <2>
+      path: classpath:server.p12
+      password: mypassword
       type: PKCS12
 ----
-<1> The `p12` file. It can also be referenced as `file:/path/to/the/file`
-<2> The password defined during the export
+- Specify the `p12` file path. It can also be referenced as `file:/path/to/the/file`
+- Also provide the `password` defined during the export
 
 With this configuration, if we start Micronaut and connect to `https://localhost:8443` we still see the warning in the browser, but if we inspect the certificate we can check that it is the one generated by Let's Encrypt.