Various documentation enhancements

docs/src/main/asciidoc/logging.adoc

@@ -200,9 +200,12 @@ See example in the <<category-named-handlers-example>> output.
 |quarkus.log.category."<category-name>".handlers=[<handler>]|empty footnote:[By default, the configured category gets the same handlers attached as the one on the root logger.]|The names of the handlers that you want to attach to a specific category.
 |===
 
-NOTE: The quotes shown in the property name are required as categories normally contain '.',
+[NOTE]
+====
+The quotes shown in the property name are required as categories normally contain '.',
 which must be escaped.
 See the example in <<category-example>>.
+====
 
 === Root logger configuration
 

docs/src/main/asciidoc/openapi-swaggerui.adoc

@@ -272,7 +272,7 @@ There are some MicroProfile OpenAPI annotations which describe global API inform
 * License
 
 All of this information (and more) can be included in your Java code by using appropriate OpenAPI annotations
-on a Jakarta REST `Application` class.  Because a JAX-RS `Application` class is not required in Quarkus, you will
+on a Jakarta REST `Application` class.  Because a Jakarta REST `Application` class is not required in Quarkus, you will
 likely have to create one.  It can simply be an empty class that extends `jakarta.ws.rs.core.Application`.  This
 empty class can then be annotated with various OpenAPI annotations such as `@OpenAPIDefinition`.  For example:
 

docs/src/main/asciidoc/qute-reference.adoc

@@ -19,7 +19,14 @@ Furthermore, Qute attempts to detect most of the template problems at build time
 
 In this guide, you will find an <<hello_world_example,introductory example>>, the description of the <<core_features,core features>> and <<quarkus_integration,Quarkus integration>> details.
 
-NOTE: Qute is primarily designed as a Quarkus extension. It is possible to use it as a "standalone" library too. However, in such case some features are not available. In general, any feature mentioned under the <<quarkus_integration>> section is missing. You can find more information about the limitations and possibilities in the <<standalone>> section.
+[NOTE]
+====
+Qute is primarily designed as a Quarkus extension.
+It is possible to use it as a "standalone" library too.
+However, in such case some features are not available.
+In general, any feature mentioned under the <<quarkus_integration>> section is missing.
+Find more information about the limitations and possibilities in the <<standalone>> section.
+====
 
 [[the_simplest_example]]
 == The Simplest Example
@@ -340,7 +347,7 @@ And afterwards value resolvers will be used to resolve "colors" against the cont
 [TIP]
 ====
 Data passed to the template instance are always accessible using the `data` namespace. 
-This could be useful to access data for which the key is overridden:  
+This could be useful to access data for which the key is overridden:
 
 [source,html]
 ----
@@ -401,22 +408,24 @@ NOTE: The current context can be accessed via the implicit binding `this`.
 |`{item.isActive ? item.name : 'Inactive item'}` outputs the value of `item.name` if `item.isActive` resolves to `true`.
 
 |Logical AND Operator
-|Outputs `true` if both parts are not `falsy` as described in the <<if_section>>. The parameter is only evaluated if needed.
+|Outputs `true` if both parts are not `falsy` as described in the <<if_section>>.
+The parameter is only evaluated if needed.
 |`{person.isActive && person.hasStyle}`
 
 |Logical OR Operator
-|Outputs `true` if any of the parts is not `falsy` as described in the <<if_section>>. The parameter is only evaluated if needed.
+|Outputs `true` if any of the parts is not `falsy` as described in the <<if_section>>.
+The parameter is only evaluated if needed.
 |`{person.isActive \|\| person.hasStyle}`
 
 |===
 
-TIP: The condition in a ternary operator evaluates to `true` if the value is not considered `falsy` as described in the <<if_section>>.
+TIP: The condition in a ternary operator evaluates to `true` if the value is not considered `falsy` as described in <<if_section>>.
 
 NOTE: In fact, the operators are implemented as "virtual methods" that consume one parameter and can be used with infix notation. For example `{person.name or 'John'}` is translated to `{person.name.or('John')}` and `{item.isActive ? item.name : 'Inactive item'}` is translated to `{item.isActive.ifTruthy(item.name).or('Inactive item')}`
 
 ==== Arrays
 
-You can iterate over elements of an array with the <<loop_section>>.
+You can iterate over elements of an array with <<loop_section>>.
 Moreover, it's also possible to get the length of the specified array and access the elements directly via an index value.
 Additionally, you can access the first/last `n` elements via the `take(n)/takeLast(n)` methods.
 
@@ -1187,7 +1196,7 @@ You can also include a fragment with an `{#include}` section inside another temp
 <1> A template identifier that contains a dollar sign `$` denotes a fragment. The `item$item_aliases` value is translated as: _Use the fragment `item_aliases` from the template `item`._
 <2> The `aliases` parameter is used to pass the relevant data. We need to make sure that the data are set correctly. In this particular case the fragment will use the expression `user.aliases` as the value of `aliases` in the `{#for alias in aliases}` section.
 
-TIP: If you want to reference a fragment from the same template you can skip the part before `$`, i.e. something like `{#include $item_aliases /}`.
+TIP: If you want to reference a fragment from the same template, skip the part before `$`, i.e. something like `{#include $item_aliases /}`.
 
 NOTE: You can specify `{#include item$item_aliases _ignoreFragments=true /}` in order to disable this feature, i.e. a dollar sign `$` in the template identifier does not result in a fragment lookup.
 
@@ -1233,7 +1242,7 @@ a lot of
 ==== Eval Section
 
 This section can be used to parse and evaluate a template dynamically.
-The behavior is very similar to the <<include_helper>> but:
+The behavior is very similar to <<include_helper>> but:
 
 1. The template content is passed directly, i.e. not obtained via an `io.quarkus.qute.TemplateLocator`,
 2. It's not possible to override parts of the evaluated template.
@@ -1253,7 +1262,7 @@ In other words, it is not possible to cache the parsed value to conserve resourc
 ==== Cached Section
 
 Sometimes it's practical to cache parts of the template that rarely change.
-In order to use the caching capability you'll need to register and configure the built-in `io.quarkus.qute.CacheSectionHelper.Factory`:
+In order to use the caching capability, register and configure the built-in `io.quarkus.qute.CacheSectionHelper.Factory`:
 
 [source,java]
 ----
@@ -1387,7 +1396,7 @@ The strict rendering enables the developers to catch insidious errors caused by
 If enabled then any expression that cannot be resolved, i.e. is evaluated to an instance of `io.quarkus.qute.Results.NotFound`, will always result in a `TemplateException` and the rendering is aborted.
 A `NotFound` value is considered an error because it basically means that no value resolver was able to resolve the expression correctly.
 
-NOTE: `null` is a valid value though. It is considered `falsy` as described in the <<if_section>> and does not produce any output.
+NOTE: `null` is a valid value though. It is considered `falsy` as described in <<if_section>> and does not produce any output.
 
 Strict rendering is enabled by default.
 However, you can disable this functionality via `io.quarkus.qute.EngineBuilder.strictRendering(boolean)`.
@@ -1404,7 +1413,7 @@ In fact, `??` is just a shorthand notation for `.or(null)`, i.e. `{#if valueNotF
 [[quarkus_integration]]
 == Quarkus Integration
 
-If you want to use Qute in your Quarkus application add the following dependency to your project:
+If you want to use Qute in your Quarkus application, add the following dependency to your project:
 
 [source,xml]
 ----
@@ -2474,7 +2483,7 @@ In the development mode, all files located in `src/main/resources/templates` are
 ==== Basic Concepts
 
 The basic idea is that every message is potentially a very simple template.
-In order to prevent type errors a message is defined as an annotated method of a *message bundle interface*.
+In order to prevent type errors, a message is defined as an annotated method of a *message bundle interface*.
 Quarkus generates the *message bundle implementation* at build time.
 
 .Message Bundle Interface Example
@@ -2491,7 +2500,7 @@ public interface AppMessages {
 }
 ----
 <1> Denotes a message bundle interface. The bundle name is defaulted to `msg` and is used as a namespace in templates expressions, e.g. `{msg:hello_name}`.
-<2> Each method must be annotated with `@Message`. The value is a qute template. If no value is provided, then a corresponding value from a localized file is taken. If no such file exists an exception is thrown and the build fails.
+<2> Each method must be annotated with `@Message`. The value is a qute template. If no value is provided, then a corresponding value from a localized file is taken. If no such file exists, an exception is thrown and the build fails.
 <3> The method parameters can be used in the template.
 
 The message bundles can be used at runtime:
@@ -2566,7 +2575,7 @@ Additionally, there are two ways to define a localized bundle:
 1. Create an interface that extends the default interface that is annotated with `@Localized`
 2. Create an UTF-8 encoded file located in the `src/main/resources/messages` directory of an application archive; e.g. `msg_de.properties`.
 
-TIP: While a localized interface enables easy refactoring an external file might be more convenient in many situations.
+TIP: While a localized interface enables easy refactoring, an external file might be more convenient in many situations.
 
 .Localized Interface Example
 [source,java]
@@ -2617,7 +2626,7 @@ hello=Hello \
 ----
 Note that the line terminator is escaped with a backslash character `\` and white space at the start of the following line is ignored. I.e. `{msg:hello('Edgar')}` would be rendered as `Hello Edgar and good morning!`.
 
-Once we have the localized bundles defined we need a way to _select_ the correct bundle for a specific template instance, i.e. to specify the locale for all message bundle expressions in the template.
+Once we have the localized bundles defined, we need a way to _select_ the correct bundle for a specific template instance, i.e. to specify the locale for all message bundle expressions in the template.
 By default, the locale specified via the `quarkus.default-locale` configuration property is used to select the bundle.
 Alternatively, you can specify the `locale` attribute of a template instance.
 

docs/src/main/asciidoc/rest-data-panache.adoc

@@ -85,7 +85,7 @@ implementation("io.quarkus:quarkus-resteasy-reactive-jackson")
 ----
 
 * Implement the Panache entities and/or repositories as explained in the xref:hibernate-orm-panache.adoc[Hibernate ORM with Panache] guide.
-* Define the interfaces for generation as explained in <<hr-generating-resources, the resource generation section>>.
+* Define the interfaces for generation as explained in the <<hr-generating-resources>> section.
 
 To see the Hibernate ORM REST Data with Panache in action, you can check out the {quickstarts-tree-url}/hibernate-orm-rest-data-panache-quickstart[hibernate-orm-rest-data-panache-quickstart] quickstart.
 
@@ -169,7 +169,8 @@ implementation("io.quarkus:quarkus-resteasy-reactive-jackson")
 
 REST Data with Panache generates Jakarta REST resources based on the interfaces available in your application.
 For each entity and repository that you want to generate, provide a resource interface.
-_Do not implement these interfaces and don't provide custom methods because they will be ignored._ You can, however, override the methods from the extended interface in order to customize them (see the section at the end).
+_Do not implement these interfaces and don't provide custom methods because they will be ignored._
+You can, however, override the methods from the extended interface in order to customize them (see the section at the end).
 
 === PanacheEntityResource
 
@@ -290,6 +291,7 @@ public class PeopleResourceJaxRs { // The actual class name is going to be uniqu
 == Resource customisation
 
 REST Data with Panache provides a `@ResourceProperties` and `@MethodProperties` annotations that can be used to customize certain features of the resource.
+
 It can be used in your resource interface:
 
 [source,java]
@@ -427,7 +429,7 @@ In this example, we have added a named query to list all the persons that contai
 
 Next, we can set a query param `namedQuery` when listing the entities using the generated resource with the name of the named query that we want to use, for example, calling `http://localhost:8080/people?namedQuery=Person.containsInName&name=ter` would return all the persons which name contains the text "ter".
 
-For more information about how named queries work, go to https://quarkus.io/guides/hibernate-orm-panache#named-queries[the Hibernate ORM] guide or to https://quarkus.io/guides/hibernate-reactive-panache#named-queries[the Hibernate Reactive] guide.
+For more information about how named queries work, go to the xref:hibernate-orm-panache.adoc#named-queries[Hibernate ORM] guide or to the xref:hibernate-reactive-panache.adoc#named-queries[Hibernate Reactive] guide.
 
 == Resource Method Before/After Listeners
 

docs/src/main/asciidoc/resteasy-reactive.adoc

@@ -265,8 +265,8 @@ see <<uri-parameters,URI parameters>> for more information.
 
 |===
 
-For each of those annotations, you may specify the name of the element they refer to, otherwise
-they will use the name of the annotated method parameter.
+For each of those annotations, you may specify the name of the element they refer to,
+otherwise, they will use the name of the annotated method parameter.
 
 If a client made the following HTTP call:
 
@@ -2829,7 +2829,7 @@ NOTE: If the client does not support HTTP compression then the response body is
 === Using Build time conditions
 
 Quarkus enables the inclusion or exclusion of Jakarta REST Resources, Providers and Features directly thanks to build time conditions in the same that it does for CDI beans.
-Thus, the various Jakarta REST classes can be annotated with profile conditions (`@io.quarkus.arc.profile.IfBuildProfile` or `@io.quarkus.arc.profile.UnlessBuildProfile`) and/or with property conditions (`io.quarkus.arc.properties.IfBuildProperty` or `io.quarkus.arc.properties.UnlessBuildProperty`) to indicate to Quarkus at build time under which conditions these JAX-RS classes should be included.
+Thus, the various Jakarta REST classes can be annotated with profile conditions (`@io.quarkus.arc.profile.IfBuildProfile` or `@io.quarkus.arc.profile.UnlessBuildProfile`) and/or with property conditions (`io.quarkus.arc.properties.IfBuildProperty` or `io.quarkus.arc.properties.UnlessBuildProperty`) to indicate to Quarkus at build time under which conditions these Jakarta REST classes should be included.
 
 In the following example, Quarkus includes the `ResourceForApp1Only` Resource class if and only if the build profile `app1` has been enabled.
 

docs/src/main/asciidoc/resteasy.adoc

@@ -790,7 +790,7 @@ An explicit CDI scope annotation (`@RequestScoped`, `@ApplicationScoped`, etc.)
 
 == Include/Exclude Jakarta REST classes with build time conditions
 
-Quarkus enables the inclusion or exclusion of JAX-RS Resources, Providers and Features directly thanks to build time conditions in the same that it does for CDI beans.
+Quarkus enables the inclusion or exclusion of Jakarta REST Resources, Providers and Features directly thanks to build time conditions in the same that it does for CDI beans.
 Thus, the various Jakarta REST classes can be annotated with profile conditions (`@io.quarkus.arc.profile.IfBuildProfile` or `@io.quarkus.arc.profile.UnlessBuildProfile`) and/or with property conditions (`io.quarkus.arc.properties.IfBuildProperty` or `io.quarkus.arc.properties.UnlessBuildProperty`) to indicate to Quarkus at build time under which conditions these Jakarta REST classes should be included.
 
 In the following example, Quarkus includes the endpoint `sayHello` if and only if the build profile `app1` has been enabled.
@@ -808,7 +808,7 @@ public class ResourceForApp1Only {
 }
 ----
 
-Please note that if a Jakarta REST Application has been detected and the method `getClasses()` and/or `getSingletons()` has/have been overridden, Quarkus will ignore the build time conditions and consider only what has been defined in the JAX-RS Application.
+Please note that if a Jakarta REST Application has been detected and the method `getClasses()` and/or `getSingletons()` has/have been overridden, Quarkus will ignore the build time conditions and consider only what has been defined in the Jakarta REST Application.
 
 == Conclusion
 

docs/src/main/asciidoc/security-authentication-mechanisms-concept.adoc

@@ -38,16 +38,16 @@ The following table maps specific authentication requirements to a supported mec
 |Kerberos ticket |link:https://quarkiverse.github.io/quarkiverse-docs/quarkus-kerberos/dev/index.html[Kerberos]
 |===
 
-See also the <<table>> table featured later in this section.
+See also the xref:table[Token authentication mechanism comparison] table featured later in this section.
 
 [[built-in-authentication-mechanisms]]
 == Built-in authentication mechanisms
 
 Quarkus Security provides the following built-in authentication support:
 
 * xref:security-basic-authentication-concept.adoc[Basic authentication]
-* <<form-auth>>
-* <<mutual-tls>>
+* xref:form-auth[Form-based authentication]
+* xref:mutual-tls[Mutual TLS authentication]
 
 === Basic authentication
 
@@ -249,7 +249,6 @@ For more information, see xref:security-jwt.adoc[Using SmallRye JWT role-based a
 For more information, see xref:security-oauth2.adoc[Using OAuth2].
 
 [[oidc-jwt-oauth2-comparison]]
-
 == Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms
 
 Use the following information to select the appropriate token authentication mechanism to secure your Quarkus applications.

docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc

@@ -248,10 +248,10 @@ s| @RolesAllowed | Specifies the list of security roles permitted to access meth
 As an equivalent to `@RolesAllowed("**")`, {project-name} also provides the `io.quarkus.security.Authenticated` annotation that permits any authenticated user to access the resource.
 |===
 
-<<subject-example>> featured in this chapter demonstrates an endpoint that uses both Jakarta REST and Common Security annotations to describe and secure its endpoints.
+xref:subject-example[SubjectExposingResource example] featured in this chapter demonstrates an endpoint that uses both Jakarta REST and Common Security annotations to describe and secure its endpoints.
 
-[#subject-example]
-.SubjectExposingResource Example
+[[subject-example]]
+.SubjectExposingResource example
 [source,java]
 ----
 import java.security.Principal;

docs/src/main/asciidoc/security-basic-authentication-howto.adoc

@@ -38,14 +38,15 @@ For more information, see xref:security-testing.adoc#configuring-user-informatio
 
 [IMPORTANT]
 ====
-Configuring user names, secrets, and roles in the `application.properties` file is only suitable for testing scenarios. If you are securing an application for production, always use a database to store this information.
+Configuring user names, secrets, and roles in the `application.properties` file is only suitable for testing scenarios.
+If you are securing an application for production, always use a database to store this information.
 ====
 
 To walk through how to configure Basic authentication together with Jakarta Persistence for storing user credentials in a database, see the xref:security-basic-authentication-tutorial.adoc[Secure a Quarkus application with Basic authentication] tutorial.
 
 == References
 
 * xref:security-overview-concept.adoc[Quarkus Security overview]
-* xref:security-identity-providers.adoc[Identity Providers]
+* xref:security-identity-providers-concept.adoc[Identity Providers]
 * xref:security-testing.adoc#configuring-user-information[Configuring User Information in application.properties]
 * xref:security-basic-authentication-concept.adoc[Basic authentication]