Improve readability of Operator guides (#20093)

Co-authored-by: Alexander Schwartz <aschwart@redhat.com>

docs/guides/operator/basic-deployment.adoc

@@ -25,11 +25,11 @@ A database should be available and accessible from the cluster namespace where K
 For a list of supported databases, see <@links.server id="db"/>.
 The Keycloak Operator does not manage the database and you need to provision it yourself. Consider verifying your cloud provider offering or using a database operator such as https://access.crunchydata.com/documentation/postgres-operator/latest/[Crunchy].
 
-For development purposes, you can use an ephemeral PostgreSQL pod installation. To provision it, enter the following commands:
+For development purposes, you can use an ephemeral PostgreSQL pod installation. To provision it, follow the approach below:
 
-[source,bash]
+Create YAML file `example-postgres.yaml`:
+[source,yaml]
 ----
-cat <<EOF >> example-postgres.yaml
 apiVersion: apps/v1
 kind: StatefulSet
 metadata:
@@ -73,7 +73,12 @@ spec:
   ports:
   - port: 5432
     targetPort: 5432
-EOF
+----
+
+Apply the changes:
+
+[source,bash]
+----
 kubectl apply -f example-postgres.yaml
 ----
 
@@ -114,11 +119,11 @@ kubectl create secret generic keycloak-db-secret \
   --from-literal=password=[your_database_password]
 ----
 
-You can customize several fields using the Keycloak CRD. However, for a basic deployment, you can enter the following example commands:
+You can customize several fields using the Keycloak CRD. For a basic deployment, you can stick to the following approach:
 
-[source,bash]
+Create YAML file `example-kc.yaml`:
+[source,yaml]
 ----
-cat <<EOF >> example-kc.yaml
 apiVersion: k8s.keycloak.org/v2alpha1
 kind: Keycloak
 metadata:
@@ -138,7 +143,12 @@ spec:
     tlsSecret: example-tls-secret
   hostname:
     hostname: test.keycloak.org
-EOF
+----
+
+Apply the changes:
+
+[source,bash]
+----
 kubectl apply -f example-kc.yaml
 ----
 
@@ -169,9 +179,10 @@ CONDITION: RollingUpdate
 The Keycloak deployment is exposed through a basic Ingress and is accessible through the provided hostname.
 If the default ingress does not fit your use case, disable it by setting `ingress` spec with `enabled` property to `false` value:
 
-[source,bash]
+Edit YAML file `example-kc.yaml`:
+
+[source,yaml]
 ----
-cat <<EOF >> example-kc.yaml
 apiVersion: k8s.keycloak.org/v2alpha1
 kind: Keycloak
 metadata:
@@ -180,7 +191,12 @@ spec:
     ...
     ingress:
       enabled: false
-EOF
+----
+
+Apply the changes:
+
+[source,bash]
+----
 kubectl apply -f example-kc.yaml
 ----
 You can provide an alternative ingress resource pointing to the service `<keycloak-cr-name>-service`.

docs/guides/operator/realm-import.adoc

@@ -48,9 +48,10 @@ The recommended way to obtain a `RealmRepresentation` is by leveraging the expor
 
 Use `kubectl` to create the CR in the correct cluster namespace:
 
-[source,bash]
+Create YAML file `example-realm-import.yaml`:
+
+[source,yaml]
 ----
-cat <<EOF >> example-realm-import.yaml
 apiVersion: k8s.keycloak.org/v2alpha1
 kind: KeycloakRealmImport
 metadata:
@@ -62,7 +63,12 @@ spec:
     realm: example-realm
     displayName: ExampleRealm
     enabled: true
-EOF
+----
+
+Apply the changes:
+
+[source,bash]
+----
 kubectl apply -f example-realm-import.yaml
 ----
 

pom.xml

@@ -35,6 +35,8 @@
     <packaging>pom</packaging>
 
     <properties>
+        <asciidoctor.plugin.version>1.5.8</asciidoctor.plugin.version>
+
         <jboss.repo.nexusUrl>https://s01.oss.sonatype.org/</jboss.repo.nexusUrl>
         <jboss.releases.repo.id>jboss-releases-repository</jboss.releases.repo.id>
         <jboss.releases.repo.url>https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/</jboss.releases.repo.url>
@@ -2088,7 +2090,7 @@
                 <plugin>
                     <groupId>org.asciidoctor</groupId>
                     <artifactId>asciidoctor-maven-plugin</artifactId>
-                    <version>1.5.8</version>
+                    <version>${asciidoctor.plugin.version}</version>
                 </plugin>
             </plugins>
         </pluginManagement>