Collapsible Blocks Feature added

Author: sarveshpandit

USAGEGUIDE.adoc

@@ -59,6 +59,33 @@ NOTE: Highlighted text for note Callout
 
 WARNING: Highlighted text for warning Callout
 
+=== Collapsible blocks (Deep dive / Hint)
+
+Use `[%collapsible]` on an *example* block so optional detail stays collapsed until the learner expands it. A title line starting with a dot (`.Title`) sets the clickable label (summary).
+
+[source,asciidoc]
+----
+.Hint
+[%collapsible]
+====
+Optional extra detail for curious readers.
+====
+
+.Deep dive: why this works
+[%collapsible]
+====
+Longer explanation, lists, or source blocks go here.
+====
+----
+
+To start expanded instead of collapsed, use `[%collapsible%open]` on the example block.
+
+Use *NOTE* and *WARNING* for short callouts everyone should read. Use collapsible blocks for longer hints or deep dives that would clutter the main lesson path.
+
+Collapsible behavior applies to the **HTML site** from Antora. PDF output from `asciidoctor-pdf` is not interactive; readers typically see all block content without expand/collapse.
+
+Live examples: link:./modules/chapter1/pages/collapsible-demo.adoc[Collapsible blocks demo].
+
 Table without header row:
 
 [cols="1,1"]
@@ -92,4 +119,5 @@ Table with header row:
 - link:./README.md[Getting started with a new training content repository]
 - link:./DEVSPACE.md[Development using devspace]
 - link:./modules/chapter1/pages/tabs-demo.adoc[Tabbed code blocks (Asciidoctor Tabs demo)]
+- link:./modules/chapter1/pages/collapsible-demo.adoc[Collapsible blocks (Deep dive / Hint demo)]
 

modules/chapter1/nav.adoc

@@ -2,4 +2,5 @@
 ** xref:section1.adoc[]
 ** xref:section2.adoc[]
 ** xref:section3.adoc[]
-** xref:tabs-demo.adoc[]
+** xref:tabs-demo.adoc[]
+** xref:collapsible-demo.adoc[]

modules/chapter1/pages/collapsible-demo.adoc

@@ -0,0 +1,37 @@
+= Collapsible blocks
+
+This page demonstrates https://docs.asciidoctor.org/asciidoc/latest/blocks/collapsible/[collapsible example blocks^] in Antora: use them for optional *Hints*, *Deep dives*, or other detail that should not block the main lesson flow.
+
+No extra Antora extension is required; `[%collapsible]` is built into Asciidoctor.
+
+== Hint (collapsed by default)
+
+.Hint
+[%collapsible]
+====
+Try the exercise first; open this only if you are stuck.
+
+* Check that your environment variables are set.
+* Re-read the previous section on configuration.
+====
+
+== Deep dive (collapsed by default)
+
+.Deep dive: how the pipeline stages relate
+[%collapsible]
+====
+The build runs *validate*, then *compile*, then *package*. Skipping a stage can leave artifacts out of date; that is why CI always runs the full chain.
+
+[source,bash]
+----
+./gradlew clean build
+----
+====
+
+== Starts expanded
+
+.Optional context
+[%collapsible%open]
+====
+This block uses `[%collapsible%open]` so it is expanded on first load. Use sparingly when the extra context is still optional but you want it visible by default.
+====

supplemental-ui/css/vendor/collapsible.css

@@ -0,0 +1,27 @@
+/* Supplemental styling for Asciidoctor [%collapsible] example blocks (HTML details/summary) */
+
+.sectionbody > details {
+  margin: 0 0 1.25em;
+  border: 1px solid #ccc;
+  border-radius: 3px;
+  overflow: hidden;
+}
+
+.sectionbody > details > summary.title {
+  padding: 0.5em 0.75em;
+  cursor: pointer;
+  font-weight: 600;
+  list-style: none;
+}
+
+.sectionbody > details > summary.title::-webkit-details-marker {
+  display: none;
+}
+
+.sectionbody > details[open] > summary.title {
+  border-bottom: 1px solid #ccc;
+}
+
+.sectionbody > details > .content {
+  padding: 0.75em 1em;
+}

supplemental-ui/partials/head-styles.hbs

@@ -1,2 +1,3 @@
     <link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css">
     <link rel="stylesheet" href="{{{uiRootPath}}}/css/vendor/tabs.css">
+    <link rel="stylesheet" href="{{{uiRootPath}}}/css/vendor/collapsible.css">