Antora playbook comments

antora-playbook.yml

@@ -1,13 +1,17 @@
 site:
+  #  https://docs.antora.org/antora/latest/playbook/set-up-playbook/#configure-your-sites-properties
   title: Documentation
   start_page: home::index.adoc
   url: https://docs.hazelcast.com
   keys:
     google_analytics: 'GTM-MQ59XD6'
+    # The following 3 parameters: id, api and index are used for
+    # Algolia docsearch setup in the hazelcast-docs-ui repo
     docsearch_id: 'QK2EAH8GB0'
     docsearch_api: 'ef7bd9485eafbd75d6e8425949eda1f5'
     docsearch_index: 'prod_hazelcast_docs'
 urls:
+  #  https://docs.antora.org/antora/latest/playbook/urls-html-extension-style/
   html_extension_style: drop
 content:
   sources:
@@ -223,15 +227,15 @@ content:
 ui:
   bundle:
     url: https://github.com/hazelcast/hazelcast-docs-ui/releases/latest/download/ui-bundle.zip
+    # https://docs.antora.org/antora/latest/playbook/set-up-playbook/#configure-your-sites-ui-bundle
+    # When snapshot is set to true, Antora will download the UI bundle
+    # whenever fetch is activated in the playbook or from the CLI.
     snapshot: true
+  #  Needed for API calls from Cloud Web App (Learning Centre page)
   supplemental_files:
     - path: netlify.toml
       contents: >
         [[headers]]
-
-
-
-
           for = "/api/*"
           [headers.values]
             Access-Control-Allow-Origin = "*"
@@ -281,7 +285,7 @@ antora:
                     - '**/hazelcast/management-center'
                 branch:
                   includes:
-                      - 'master'
+                    - 'master'
         - name: management-center
           version: '5.5'
           mappings:
@@ -293,7 +297,7 @@ antora:
                     - '**/hazelcast/management-center'
                 branch:
                   includes:
-                      - '5.5.0'
+                    - '5.5.0'
         - name: management-center
           version: '5.3'
           mappings:
@@ -342,6 +346,7 @@ antora:
                   branch:
                     includes:
                       - '5.4.0'
+    #  Needed for API calls from Cloud Web App (Learning Centre page)
     - require: ./lib/api_json.js
       tags:
         - Favorites
@@ -372,9 +377,12 @@ asciidoc:
     # Order the products in the version selector dropdown.
     # Use * to list all remaining products in alphabetical order.
     page-component-order: 'hazelcast, management-center, cloud, *'
+    # https://docs.antora.org/antora/latest/playbook/asciidoc-attributes/#precedence-rules
+    # page-pagination is soft-set to true
     page-pagination: true@
     # Allows us to use UI macros. See https://docs.asciidoctor.org/asciidoc/latest/macros/ui-macros/
     page-experimental: true
+    # AsciiDoc ID settings https://docs.asciidoctor.org/asciidoc/latest/sections/id-prefix-and-separator/
     idprefix: ''
     idseparator: '-'
     imdg-javadoc: https://docs.hazelcast.org/docs/latest-dev/javadoc