From d47a219e7caa62c716e018d0e3cecbdb5f4caa84 Mon Sep 17 00:00:00 2001
From: Mykola Fant <mykola.fant@hazelcast.com>
Date: Wed, 23 Oct 2024 10:09:51 +0300
Subject: [PATCH] Antora playbook comments (#393)

- Comment config details
---
 antora-playbook.yml | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/antora-playbook.yml b/antora-playbook.yml
index 64a57e88..03285d71 100644
--- a/antora-playbook.yml
+++ b/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:
@@ -19,7 +23,7 @@ content:
       start_path: docs
     - url: https://github.com/hazelcast/hz-flow-docs
       branches: [main]
-      start_path: docs         
+      start_path: docs
     - url: https://github.com/hazelcast/imdg-docs
       branches: [v/*]
       start_path: docs
@@ -224,19 +228,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 = "*"
@@ -371,6 +371,7 @@ antora:
                   branch:
                     includes:
                       - 5.6.0
+    #  Needed for API calls from Cloud Web App (Learning Centre page)
     - require: ./lib/api_json.js
       tags:
         - Favorites
@@ -401,9 +402,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