From fb79bddbc6faeadf98c5fd6ff4d9f6a28a6c0ab8 Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Thu, 22 Jan 2026 14:41:07 +0100
Subject: [PATCH 01/16] fix table captions

---
 .../benchmarking/json_report/templates/macros/table.adoc.j2 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2
index 9d22dd8b9..baf3eb709 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2
@@ -4,13 +4,13 @@
 {%set table = table_controller.generate() %}
 
 
-{% if tableNode.caption %}
-.{{tableNode.caption}}
-{% endif %}
 {% if tableNode.style.classnames %}
 [{% for classname in tableNode.style.classnames %}.{{classname}}{% endfor %}]
 {% endif %}
 --
+{% if tableNode.caption %}
+.{{tableNode.caption}}
+{% endif %}
 [cols="{{ table_controller.getColsAlignment() }}",options="header"]
 |===
 

From 1fbb7305ecf34b5f486ca527104bd28149bdfd93 Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Thu, 22 Jan 2026 15:00:11 +0100
Subject: [PATCH 02/16] support captions in plots ( workaraound with example
 blocks )

---
 docs/antora/supplemental-ui/css/figures.css   | 24 ++++++++++++++++++-
 .../json_report/schemas/jsonReport.py         |  1 +
 .../templates/json2adoc_report.adoc.j2        |  1 +
 .../json_report/templates/macros/plot.adoc.j2 |  8 +++++++
 .../reframe/schemas/defaultJsonReport.py      |  3 ++-
 5 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/docs/antora/supplemental-ui/css/figures.css b/docs/antora/supplemental-ui/css/figures.css
index e0aed6204..f7f0b7c35 100644
--- a/docs/antora/supplemental-ui/css/figures.css
+++ b/docs/antora/supplemental-ui/css/figures.css
@@ -75,4 +75,26 @@
 
 .export-container button:hover {
     background-color: #005fa3;
-}
\ No newline at end of file
+}
+
+/* Example block styling for plots */
+.exampleblock.plot {
+  border: none;
+  padding: 0;
+  margin: 0;
+}
+
+.exampleblock.plot > .content {
+  padding: 0;
+  border: none;
+}
+
+.exampleblock.plot > .title {
+  text-align: center;
+  font-style: italic;
+  margin-top: 0.5rem;
+}
+
+.exampleblock.example {
+  border-left: 4px solid var(--brand-primary);
+}
diff --git a/src/feelpp/benchmarking/json_report/schemas/jsonReport.py b/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
index 07fe90c00..6b4228566 100644
--- a/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
+++ b/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
@@ -30,6 +30,7 @@ class ImageNode(ReportNode):
 
 class PlotNode(ReportNode):
     type: Literal["plot"]
+    caption: Optional[str] = None
     plot: Plot
 
 
diff --git a/src/feelpp/benchmarking/json_report/templates/json2adoc_report.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/json2adoc_report.adoc.j2
index 0340d76b6..25e53a353 100644
--- a/src/feelpp/benchmarking/json_report/templates/json2adoc_report.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/json2adoc_report.adoc.j2
@@ -1,3 +1,4 @@
+:example-caption: Plot
 {% if report.description %}
 :description: {{ report.description }}
 {% endif %}
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
index 8660519bf..083ed351e 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
@@ -1,5 +1,12 @@
 {% macro render(plotNode,data) %}
 
+
+
+[example.plot]
+{%if plotNode.caption %}
+.{{plotNode.caption}}
+{% endif %}
+====
 ++++
 
 {% for figure in FiguresController(data.get(plotNode.ref),plotNode.plot).generateAll() %}
@@ -32,5 +39,6 @@
 {% endfor %}
 
 ++++
+====
 
 {% endmacro %}
\ No newline at end of file
diff --git a/src/feelpp/benchmarking/reframe/schemas/defaultJsonReport.py b/src/feelpp/benchmarking/reframe/schemas/defaultJsonReport.py
index 6db87b007..799edb2b8 100644
--- a/src/feelpp/benchmarking/reframe/schemas/defaultJsonReport.py
+++ b/src/feelpp/benchmarking/reframe/schemas/defaultJsonReport.py
@@ -80,7 +80,8 @@ def applyDefaultPlots(cls, values):
                         item = {
                             "type": "plot",
                             "ref":"reframe_df",
-                            "plot": DefaultPlot.model_validate(item["plot"])
+                            "plot": DefaultPlot.model_validate(item["plot"]),
+                            "caption": item.get("caption", None)
                         }
                     elif isinstance(item, dict) and (item.get("type") == "section" or item.get("type")=="grid"):
                         item = cls.applyDefaultPlots(item)

From ac5fbc1832435c46fc7f2b801addfb508f3fe385 Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Thu, 22 Jan 2026 15:09:11 +0100
Subject: [PATCH 03/16] flip caption below plot

---
 docs/antora/supplemental-ui/css/figures.css | 26 ++++++++++++---------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/docs/antora/supplemental-ui/css/figures.css b/docs/antora/supplemental-ui/css/figures.css
index f7f0b7c35..cb178f340 100644
--- a/docs/antora/supplemental-ui/css/figures.css
+++ b/docs/antora/supplemental-ui/css/figures.css
@@ -79,22 +79,26 @@
 
 /* Example block styling for plots */
 .exampleblock.plot {
-  border: none;
-  padding: 0;
-  margin: 0;
+    border: none;
+    padding: 0;
+    margin: 0;
+    display: flex;
+    flex-direction: column;
 }
 
-.exampleblock.plot > .content {
-  padding: 0;
-  border: none;
+.exampleblock.plot>.content {
+    order: 1;
+    padding: 0;
+    border: none;
 }
 
-.exampleblock.plot > .title {
-  text-align: center;
-  font-style: italic;
-  margin-top: 0.5rem;
+.exampleblock.plot>.title {
+    order: 2;
+    text-align: center;
+    font-style: italic;
+    margin-top: 0.5rem;
 }
 
 .exampleblock.example {
-  border-left: 4px solid var(--brand-primary);
+    border-left: 4px solid var(--brand-primary);
 }

From 8b2ada0f4cf6e62fa78ce9df543da3401f0e690c Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Thu, 22 Jan 2026 15:18:50 +0100
Subject: [PATCH 04/16] handle cross references

---
 .../benchmarking/json_report/templates/macros/image.adoc.j2    | 1 +
 .../benchmarking/json_report/templates/macros/plot.adoc.j2     | 3 +++
 .../benchmarking/json_report/templates/macros/table.adoc.j2    | 1 +
 3 files changed, 5 insertions(+)

diff --git a/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2
index 88c221a09..a094c2e65 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2
@@ -4,6 +4,7 @@
 {% set styles = imageNode.style | join(' ')%}
 
 {% if imageNode.caption %}
+[[{{imageNode.caption | replace(' ','-')}}]]
 image::{{src}}[role="{{styles}}",alt={{alt}},title={{imageNode.caption}}]
 {% else %}
 image::{{src}}[role=""{{styles}}"",alt={{alt}}]
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
index 083ed351e..1280067a8 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
@@ -2,6 +2,9 @@
 
 
 
+{%if plotNode.caption %}
+[[{{plotNode.caption | replace(' ','-')}}]]
+{% endif %}
 [example.plot]
 {%if plotNode.caption %}
 .{{plotNode.caption}}
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2
index baf3eb709..3db299227 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2
@@ -9,6 +9,7 @@
 {% endif %}
 --
 {% if tableNode.caption %}
+[[{{tableNode.caption | replace(' ','-')}}]]
 .{{tableNode.caption}}
 {% endif %}
 [cols="{{ table_controller.getColsAlignment() }}",options="header"]

From 0bf9a0c136b97e66596ec60d73292bbac8e1f6c0 Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Thu, 22 Jan 2026 15:33:53 +0100
Subject: [PATCH 05/16] add id for nodes !

---
 src/feelpp/benchmarking/json_report/schemas/jsonReport.py   | 1 +
 .../benchmarking/json_report/templates/macros/image.adoc.j2 | 6 +++++-
 .../benchmarking/json_report/templates/macros/plot.adoc.j2  | 4 +++-
 .../benchmarking/json_report/templates/macros/table.adoc.j2 | 6 +++++-
 4 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/feelpp/benchmarking/json_report/schemas/jsonReport.py b/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
index 6b4228566..ff1ca3f47 100644
--- a/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
+++ b/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
@@ -8,6 +8,7 @@
 
 class ReportNode(BaseModel):
     type:str
+    id: Optional[str] = None
     ref: Optional[str] = None
 
     model_config = ConfigDict( extra="forbid" )
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2
index a094c2e65..938d092b3 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2
@@ -3,8 +3,12 @@
 {% set alt = imageNode.alt or imageNode.caption or "" %}
 {% set styles = imageNode.style | join(' ')%}
 
-{% if imageNode.caption %}
+{% if imageNode.id %}
+[[{{imageNode.id}}]]
+{% elif imageNode.caption %}
 [[{{imageNode.caption | replace(' ','-')}}]]
+{% endif %}
+{% if imageNode.caption %}
 image::{{src}}[role="{{styles}}",alt={{alt}},title={{imageNode.caption}}]
 {% else %}
 image::{{src}}[role=""{{styles}}"",alt={{alt}}]
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
index 1280067a8..3a97dc5b2 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
@@ -2,7 +2,9 @@
 
 
 
-{%if plotNode.caption %}
+{% if plotNode.id %}
+[[{{plotNode.id}}]]
+{% elif plotNode.caption %}
 [[{{plotNode.caption | replace(' ','-')}}]]
 {% endif %}
 [example.plot]
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2
index 3db299227..58506cbf7 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/table.adoc.j2
@@ -8,8 +8,12 @@
 [{% for classname in tableNode.style.classnames %}.{{classname}}{% endfor %}]
 {% endif %}
 --
-{% if tableNode.caption %}
+{% if tableNode.id %}
+[[{{tableNode.id}}]]
+{% elif tableNode.caption %}
 [[{{tableNode.caption | replace(' ','-')}}]]
+{% endif %}
+{% if tableNode.caption %}
 .{{tableNode.caption}}
 {% endif %}
 [cols="{{ table_controller.getColsAlignment() }}",options="header"]

From 77febebc72aac5d46ed0ca28da1b628d48670c9b Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Thu, 22 Jan 2026 15:36:03 +0100
Subject: [PATCH 06/16] sections can be referenced now via ID

---
 .../benchmarking/json_report/templates/macros/section.adoc.j2  | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/feelpp/benchmarking/json_report/templates/macros/section.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/section.adoc.j2
index d04566a27..2b801fe0b 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/section.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/section.adoc.j2
@@ -17,6 +17,9 @@
 
 {% macro render(sectionNode, report_data, level=1) %}
 
+{% if sectionNode.id %}
+[[{{sectionNode.id}}]]
+{% endif %}
 {%if sectionNode.title %}
 {{ '=' * level }} {{ sectionNode.title }}
 {%endif%}

From 0c764a90178fcfac50e2f13d4fc69c7e7d8cc674 Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Thu, 22 Jan 2026 16:03:28 +0100
Subject: [PATCH 07/16] support latex refs

---
 .../benchmarking/json_report/schemas/jsonReport.py       | 1 +
 .../json_report/templates/macros/latex.adoc.j2           | 9 +++++++++
 2 files changed, 10 insertions(+)

diff --git a/src/feelpp/benchmarking/json_report/schemas/jsonReport.py b/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
index ff1ca3f47..e082eff5e 100644
--- a/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
+++ b/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
@@ -20,6 +20,7 @@ class TextNode(ReportNode):
 
 class LatexNode(ReportNode):
     type:Literal["latex"]
+    is_equation: Optional[bool] = False
     latex: str
 
 class ImageNode(ReportNode):
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/latex.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/latex.adoc.j2
index cdfebdf1e..795bb455c 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/latex.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/latex.adoc.j2
@@ -1,8 +1,17 @@
 {% macro render(latexNode,data) %}
 
+{% if latexNode.id %}
+[[{{latexNode.id}}]]
+{% endif %}
 [stem]
 ++++
+{%if latexNode.is_equation %}
+\begin{equation}
 {{ latexNode.latex }}
+\end{equation}
+{% else %}
+{{ latexNode.latex }}
+{% endif %}
 ++++
 
 {% endmacro %}
\ No newline at end of file

From 3f773409a92146256699946e9068734a27d065df Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Thu, 22 Jan 2026 16:09:13 +0100
Subject: [PATCH 08/16] refs to text and itemize

---
 .../benchmarking/json_report/templates/macros/itemize.adoc.j2  | 3 +++
 .../benchmarking/json_report/templates/macros/text.adoc.j2     | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/src/feelpp/benchmarking/json_report/templates/macros/itemize.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/itemize.adoc.j2
index 25e2d2e2a..e828e3dd2 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/itemize.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/itemize.adoc.j2
@@ -2,6 +2,9 @@
 
 {% macro render(listNode,data) %}
 
+{% if listNode.id %}
+[[{{listNode.id}}]]
+{% endif %}
 {% for item in listNode.items %}
 - {{text.render(item,data)}}
 {% endfor %}
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/text.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/text.adoc.j2
index 37eeda3f2..e952e14d7 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/text.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/text.adoc.j2
@@ -1,3 +1,6 @@
 {% macro render(textNode,data) %}
+{%if textNode.id %}
+[[{{textNode.id}}]]
+{% endif %}
 {{ TextController((data or {}).get(textNode.ref),textNode.text).generate() }}
 {% endmacro %}
\ No newline at end of file

From fb64cd91223a673cd1be3bd3126450a9b295aed6 Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Thu, 22 Jan 2026 16:14:19 +0100
Subject: [PATCH 09/16] up golden files

---
 .../json_report/tests/data/golden/basic_text.adoc        | 1 +
 .../json_report/tests/data/golden/list_with_data.adoc    | 1 +
 .../json_report/tests/data/golden/plot_features.adoc     | 9 ++++++++-
 .../json_report/tests/data/golden/preprocessor.adoc      | 1 +
 .../json_report/tests/data/golden/report.adoc            | 9 +++++++--
 .../json_report/tests/data/golden/table_features.adoc    | 1 +
 6 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/basic_text.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/basic_text.adoc
index 855535a60..e3b1a3103 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/basic_text.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/basic_text.adoc
@@ -1,3 +1,4 @@
+:example-caption: Plot
 :docdatetime: <TIMESTAMP>
 
 == Introduction
diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/list_with_data.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/list_with_data.adoc
index 2586d7ebc..82c8d8220 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/list_with_data.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/list_with_data.adoc
@@ -1,3 +1,4 @@
+:example-caption: Plot
 :docdatetime: <TIMESTAMP>
 
 == Metadata
diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/plot_features.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/plot_features.adoc
index 6c080f5b0..6085fee51 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/plot_features.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/plot_features.adoc
@@ -1,7 +1,10 @@
+:example-caption: Plot
 :docdatetime: <TIMESTAMP>
 
 == Score Analysis
 
+[example.plot]
+====
 ++++
 
 <div class='figure-container'>
@@ -19,9 +22,13 @@
 </div>
 
 ++++
+====
 
 
 
+
+[example.plot]
+====
 ++++
 
 <div class='figure-container'>
@@ -58,7 +65,7 @@
 
 
 ++++
-
+====
 
 The scatter plot shows the average score per subject for each student, while the stacked bar plot visualizes how many subjects each student passed.
 
diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/preprocessor.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/preprocessor.adoc
index 307df8f72..af3a30d7b 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/preprocessor.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/preprocessor.adoc
@@ -1,3 +1,4 @@
+:example-caption: Plot
 :docdatetime: <TIMESTAMP>
 
 Processed Text: Foo Foo Baz
diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/report.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/report.adoc
index 9b462f10f..058d0cc6b 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/report.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/report.adoc
@@ -1,3 +1,4 @@
+:example-caption: Plot
 :docdatetime: <TIMESTAMP>
 
 
@@ -94,6 +95,8 @@ Placeholders in this report allow dynamic insertion of values from the datasets.
 == Performance Analysis
 
 
+[example.plot]
+====
 ++++
 
 <div class='figure-container'>
@@ -111,9 +114,11 @@ Placeholders in this report allow dynamic insertion of values from the datasets.
 </div>
 
 ++++
+====
 
 
-
+[example.plot]
+====
 ++++
 
 <div class='figure-container'>
@@ -131,7 +136,7 @@ Placeholders in this report allow dynamic insertion of values from the datasets.
 </div>
 
 ++++
-
+====
 
 The scatter plot shows average scores per subject, while the bar chart shows average attendance rates for each student.
 
diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/table_features.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/table_features.adoc
index 80d5f4e20..034eb6221 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/table_features.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/table_features.adoc
@@ -1,3 +1,4 @@
+:example-caption: Plot
 :docdatetime: <TIMESTAMP>
 
 == Student Performance

From 04b1b3b31100ca9cbad1ce23b2d3a65a54e557b8 Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Fri, 23 Jan 2026 11:04:00 +0100
Subject: [PATCH 10/16] handle grid captions and inner figures

---
 docs/antora/supplemental-ui/css/figures.css   |  6 +--
 .../json_report/schemas/jsonReport.py         |  1 +
 .../templates/json2adoc_report.adoc.j2        |  2 +-
 .../json_report/templates/macros/grid.adoc.j2 | 39 ++++++++++++-------
 .../templates/macros/image.adoc.j2            | 15 ++++---
 5 files changed, 40 insertions(+), 23 deletions(-)

diff --git a/docs/antora/supplemental-ui/css/figures.css b/docs/antora/supplemental-ui/css/figures.css
index cb178f340..c122340d2 100644
--- a/docs/antora/supplemental-ui/css/figures.css
+++ b/docs/antora/supplemental-ui/css/figures.css
@@ -78,7 +78,7 @@
 }
 
 /* Example block styling for plots */
-.exampleblock.plot {
+.exampleblock.plot,.exampleblock.grid,.exampleblock.image {
     border: none;
     padding: 0;
     margin: 0;
@@ -86,13 +86,13 @@
     flex-direction: column;
 }
 
-.exampleblock.plot>.content {
+.exampleblock.plot>.content,.exampleblock.grid>.content ,.exampleblock.image>.content {
     order: 1;
     padding: 0;
     border: none;
 }
 
-.exampleblock.plot>.title {
+.exampleblock.plot>.title,.exampleblock.grid>.title,.exampleblock.image>.title{
     order: 2;
     text-align: center;
     font-style: italic;
diff --git a/src/feelpp/benchmarking/json_report/schemas/jsonReport.py b/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
index e082eff5e..950b2ca5a 100644
--- a/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
+++ b/src/feelpp/benchmarking/json_report/schemas/jsonReport.py
@@ -71,6 +71,7 @@ class SectionNode(ReportNode):
 class GridNode(ReportNode):
     type: Literal["grid"]
     contents: Optional[List[Node]] = []
+    caption: Optional[str] = None
     columns: Optional[int] = 1
     justify: Optional[Literal["start","center","end"]] = "start"
     align: Optional[Literal["start","center","end"]] = "start"
diff --git a/src/feelpp/benchmarking/json_report/templates/json2adoc_report.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/json2adoc_report.adoc.j2
index 25e53a353..4fa47bf99 100644
--- a/src/feelpp/benchmarking/json_report/templates/json2adoc_report.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/json2adoc_report.adoc.j2
@@ -1,4 +1,4 @@
-:example-caption: Plot
+:example-caption: Figure
 {% if report.description %}
 :description: {{ report.description }}
 {% endif %}
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/grid.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/grid.adoc.j2
index 42db4b9bd..c67ada82b 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/grid.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/grid.adoc.j2
@@ -5,23 +5,34 @@
 {% import "macros/table.adoc.j2" as table %}
 {% import "macros/itemize.adoc.j2"  as itemize %}
 
-{% set handlers = {
-    "plot":   plot.render,
-    "text":   text.render,
-    "image":  image.render,
-    "latex":  latex.render,
-    "table": table.render,
-    "itemize": itemize.render
-} %}
-
 {% macro render(gridNode,report_data) %}
-[.grid.grid-{{gridNode.columns}}.grid-{{gridNode.gap}}.justify-{{gridNode.justify}}.align-{{gridNode.align}}]
+{% if gridNode.id %}
+[[{{gridNode.id}}]]
+{% endif %}
+[example.grid]
+{% if gridNode.caption %}
+.{{gridNode.caption}}
+{% endif %}
+====
+[.grid.grid-{{gridNode.columns}}.gap-{{gridNode.gap}}.justify-{{gridNode.justify}}.align-{{gridNode.align}}]
 --
+:figure-caption!:
 {%for node in gridNode.contents%}
-{% set handler = handlers.get(node.type) %}
-{% if handler %}
-{{ handler(node,report_data.get(node.ref)) }}
+{% if node.type == "image" %}
+{{ image.render(node,report_data.get(node.ref), make_block=False) }}
+{% elif node.type == "plot" %}
+{{ plot.render(node,report_data.get(node.ref)) }}
+{% elif node.type == "latex" %}
+{{ latex.render(node,report_data.get(node.ref)) }}
+{% elif node.type == "text" %}
+{{ text.render(node,report_data.get(node.ref)) }}
+{% elif node.type == "table" %}
+{{ table.render(node,report_data.get(node.ref)) }}
+{% elif node.type == "itemize" %}
+{{ itemize.render(node,report_data.get(node.ref)) }}
 {% endif %}
 {% endfor %}
+:figure-caption: Figure
 --
-{% endmacro %}
+====
+{% endmacro %}
\ No newline at end of file
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2
index 938d092b3..bf5305e7f 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/image.adoc.j2
@@ -1,4 +1,4 @@
-{% macro render(imageNode,data) %}
+{% macro render(imageNode,data,make_block = True) %}
 {% set src = imageNode.src %}
 {% set alt = imageNode.alt or imageNode.caption or "" %}
 {% set styles = imageNode.style | join(' ')%}
@@ -6,12 +6,17 @@
 {% if imageNode.id %}
 [[{{imageNode.id}}]]
 {% elif imageNode.caption %}
-[[{{imageNode.caption | replace(' ','-')}}]]
+[[{{imageNode.caption | replace(' ','-') | replace('(','') | replace(')','') }}]]
 {% endif %}
 {% if imageNode.caption %}
-image::{{src}}[role="{{styles}}",alt={{alt}},title={{imageNode.caption}}]
+.{{imageNode.caption}}
+{% endif %}
+{% if make_block %}
+[example.image]
+====
+image::{{src}}[role="{{styles}}",alt={{alt}}]
+====
 {% else %}
-image::{{src}}[role=""{{styles}}"",alt={{alt}}]
+image::{{src}}[role="{{styles}}",alt={{alt}}]
 {% endif %}
-
 {% endmacro %}

From 587512f6cb39b247916e4e9d1c0863a6cc2b07e1 Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Fri, 23 Jan 2026 11:37:38 +0100
Subject: [PATCH 11/16] improve plot style and support plots in grid #381

---
 docs/antora/supplemental-ui/css/figures.css   | 87 ++++++++++---------
 .../json_report/templates/macros/grid.adoc.j2 |  2 +-
 .../json_report/templates/macros/plot.adoc.j2 | 11 ++-
 3 files changed, 54 insertions(+), 46 deletions(-)

diff --git a/docs/antora/supplemental-ui/css/figures.css b/docs/antora/supplemental-ui/css/figures.css
index c122340d2..e276dfcaa 100644
--- a/docs/antora/supplemental-ui/css/figures.css
+++ b/docs/antora/supplemental-ui/css/figures.css
@@ -1,31 +1,26 @@
 .figure-container {
     position: relative;
-    margin: 1.5rem auto;
-    padding: 1rem;
-    background-color: #fff;
-    border: 1px solid #ddd;
-    border-radius: 8px;
-    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.08);
+    width: 100%;
+    max-width: 100%;
+    box-sizing: border-box;
+    margin: 1.2rem 0;
+    background: none;
+    box-shadow: none;
+    padding: 0.5rem;
+    border: 1px solid #ccc;
+    border-radius: 4px;
 }
 
 .subfigure-container {
     position: absolute;
-    top: 0;
-    left: 0;
-    width: 100%;
-    height: 100%;
-    background-color: #f9f9f9;
-    padding: 1rem;
-    border: 1px solid #ddd;
-    border-top: none;
-    border-radius: 0 0 8px 8px;
+    inset: 0;
+    background: none;
+    padding: 0;
+    border: none;
 }
 
 .subfigure-container.active {
     position: relative;
-    opacity: 1;
-    pointer-events: auto;
-    z-index: 1;
 }
 
 .subfigure-container.inactive {
@@ -37,51 +32,59 @@
 /* Tabs container: display buttons inline with a bottom border to indicate grouping */
 .tabs-container {
     display: flex;
-    border-bottom: 2px solid #007acc;
-    margin-bottom: 0.5rem;
+    justify-content: flex-start;
+    gap: 0;
+    margin-bottom: 0.4rem;
 }
 
-/* Figure tab button styling */
+
 .figure-tab {
-    background: transparent;
+    background: none;
     border: none;
-    outline: none;
-    padding: 0.5rem 1rem;
-    margin-right: 0.3rem;
-    font-size: 1rem;
-    color: #007acc;
+    font-size: 0.9rem;
+    color: #444;
     cursor: pointer;
-    border-radius: 4px 4px 0 0;
-    transition: background-color 0.2s ease, color 0.2s ease;
+    border: 1px solid #ccc;
+    padding: 0.2rem 0.5rem;
 }
 
-.figure-tab:hover,
-.figure-tab.active {
-    background-color: #007acc;
-    color: #fff;
+.figure-tab:hover {
+    color: #000;               /* subtle darkening on hover */
+    background: none;          /* no hover background */
+}
+
+
+.export-container {
+    display: flex;
+    justify-content: flex-end;
+    gap: 0.3rem;
+    margin-bottom: 0.3rem;
 }
 
 .export-container button {
-    background-color: #007acc;
-    color: #fff;
+    background: none;
+    color: #666;
     border: none;
-    padding: 0.4rem 0.8rem;
-    margin-right: 0.4rem;
-    border-radius: 4px;
+    padding: 0;
+    font-size: 0.75rem;
     cursor: pointer;
-    font-size: 0.9rem;
-    transition: background-color 0.2s ease;
+    text-decoration: underline;
 }
 
 .export-container button:hover {
-    background-color: #005fa3;
+    color: #000;
+}
+
+.exampleblock.plot{
+    border: 1px solid #ccc;
+    border-radius: 4px;
 }
 
 /* Example block styling for plots */
 .exampleblock.plot,.exampleblock.grid,.exampleblock.image {
     border: none;
     padding: 0;
-    margin: 0;
+    margin: 1.5rem 0;
     display: flex;
     flex-direction: column;
 }
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/grid.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/grid.adoc.j2
index c67ada82b..1412541b9 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/grid.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/grid.adoc.j2
@@ -21,7 +21,7 @@
 {% if node.type == "image" %}
 {{ image.render(node,report_data.get(node.ref), make_block=False) }}
 {% elif node.type == "plot" %}
-{{ plot.render(node,report_data.get(node.ref)) }}
+{{ plot.render(node,report_data.get(node.ref), make_block=False) }}
 {% elif node.type == "latex" %}
 {{ latex.render(node,report_data.get(node.ref)) }}
 {% elif node.type == "text" %}
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
index 3a97dc5b2..e68e14f0e 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
@@ -1,5 +1,4 @@
-{% macro render(plotNode,data) %}
-
+{% macro render(plotNode,data, make_block=True) %}
 
 
 {% if plotNode.id %}
@@ -7,11 +6,15 @@
 {% elif plotNode.caption %}
 [[{{plotNode.caption | replace(' ','-')}}]]
 {% endif %}
+{% if make_block %}
 [example.plot]
+{% endif %}
 {%if plotNode.caption %}
 .{{plotNode.caption}}
 {% endif %}
+{% if make_block %}
 ====
+{% endif %}
 ++++
 
 {% for figure in FiguresController(data.get(plotNode.ref),plotNode.plot).generateAll() %}
@@ -27,6 +30,7 @@
 
     {% for subfigure in figure.subfigures %}
       <div class="subfigure-container {% if loop.first %}active{% else %}inactive{% endif %}" data-subfigure="{{loop.index}}">
+        {{subfigure.html}}
 
         <div class='export-container'>
         {% for export in subfigure.exports %}
@@ -36,7 +40,6 @@
         {% endfor %}
         </div>
 
-        {{subfigure.html}}
     </div>
     {% endfor %}
 </div>
@@ -44,6 +47,8 @@
 {% endfor %}
 
 ++++
+{% if make_block %}
 ====
+{% endif %}
 
 {% endmacro %}
\ No newline at end of file

From d42fa86b7bdd2dc288f76018d3e21fe937874239 Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Fri, 23 Jan 2026 11:53:57 +0100
Subject: [PATCH 12/16] emulate grid figures caption

---
 docs/antora/supplemental-ui/css/figures.css                 | 2 +-
 .../benchmarking/json_report/templates/macros/plot.adoc.j2  | 6 ++++--
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/antora/supplemental-ui/css/figures.css b/docs/antora/supplemental-ui/css/figures.css
index e276dfcaa..206253178 100644
--- a/docs/antora/supplemental-ui/css/figures.css
+++ b/docs/antora/supplemental-ui/css/figures.css
@@ -95,7 +95,7 @@
     border: none;
 }
 
-.exampleblock.plot>.title,.exampleblock.grid>.title,.exampleblock.image>.title{
+.exampleblock.plot>.title,.exampleblock.grid>.title,.exampleblock.image>.title, .plotly-figure-caption{
     order: 2;
     text-align: center;
     font-style: italic;
diff --git a/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2 b/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
index e68e14f0e..3d1611787 100644
--- a/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
+++ b/src/feelpp/benchmarking/json_report/templates/macros/plot.adoc.j2
@@ -8,11 +8,9 @@
 {% endif %}
 {% if make_block %}
 [example.plot]
-{% endif %}
 {%if plotNode.caption %}
 .{{plotNode.caption}}
 {% endif %}
-{% if make_block %}
 ====
 {% endif %}
 ++++
@@ -42,6 +40,10 @@
 
     </div>
     {% endfor %}
+
+    {%if plotNode.caption and make_block==False %}
+    <div class='plotly-figure-caption title'>{{plotNode.caption}}</div>
+    {% endif %}
 </div>
 
 {% endfor %}

From c38093dc243434f05fdf9d5b9f5b11ab09a2582c Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Fri, 23 Jan 2026 13:14:29 +0100
Subject: [PATCH 13/16] fix golden files

---
 .../tests/data/golden/basic_text.adoc         |  2 +-
 .../tests/data/golden/list_with_data.adoc     |  2 +-
 .../tests/data/golden/plot_features.adoc      | 27 +++++++++----------
 .../tests/data/golden/preprocessor.adoc       |  2 +-
 .../json_report/tests/data/golden/report.adoc | 18 ++++++-------
 .../tests/data/golden/table_features.adoc     |  2 +-
 6 files changed, 26 insertions(+), 27 deletions(-)

diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/basic_text.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/basic_text.adoc
index e3b1a3103..0eafa3059 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/basic_text.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/basic_text.adoc
@@ -1,4 +1,4 @@
-:example-caption: Plot
+:example-caption: Figure
 :docdatetime: <TIMESTAMP>
 
 == Introduction
diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/list_with_data.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/list_with_data.adoc
index 82c8d8220..8992f2fa5 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/list_with_data.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/list_with_data.adoc
@@ -1,4 +1,4 @@
-:example-caption: Plot
+:example-caption: Figure
 :docdatetime: <TIMESTAMP>
 
 == Metadata
diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/plot_features.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/plot_features.adoc
index 6085fee51..eef395eda 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/plot_features.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/plot_features.adoc
@@ -1,4 +1,4 @@
-:example-caption: Plot
+:example-caption: Figure
 :docdatetime: <TIMESTAMP>
 
 == Score Analysis
@@ -10,14 +10,14 @@
 <div class='figure-container'>
 
       <div class="subfigure-container active" data-subfigure="1">
-        <div class='export-container'>
-            <button class="csv-btn">CSV</button>
-            <button class="latex-btn">LaTeX</button>
-        </div>
         <div>
             <div>FIGURE</div>
             <script></script>
         </div>
+        <div class='export-container'>
+            <button class="csv-btn">CSV</button>
+            <button class="latex-btn">LaTeX</button>
+        </div>
     </div>
 </div>
 
@@ -38,27 +38,26 @@
     </div>
 
       <div class="subfigure-container active" data-subfigure="1">
-
-        <div class='export-container'>
-            <button>CSV</button>
-            <button>LaTeX</button>
-        </div>
         <div>
             <div>FIGURE</div>
             <script></script>
         </div>
-
-    </div>
-      <div class="subfigure-container inactive" data-subfigure="2">
-
         <div class='export-container'>
             <button>CSV</button>
             <button>LaTeX</button>
         </div>
+
+    </div>
+
+      <div class="subfigure-container inactive" data-subfigure="2">
         <div>
             <div>FIGURE</div>
             <script></script>
         </div>
+        <div class='export-container'>
+            <button>CSV</button>
+            <button>LaTeX</button>
+        </div>
 
     </div>
 </div>
diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/preprocessor.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/preprocessor.adoc
index af3a30d7b..6b7c4d16c 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/preprocessor.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/preprocessor.adoc
@@ -1,4 +1,4 @@
-:example-caption: Plot
+:example-caption: Figure
 :docdatetime: <TIMESTAMP>
 
 Processed Text: Foo Foo Baz
diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/report.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/report.adoc
index 058d0cc6b..0146176db 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/report.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/report.adoc
@@ -1,4 +1,4 @@
-:example-caption: Plot
+:example-caption: Figure
 :docdatetime: <TIMESTAMP>
 
 
@@ -102,14 +102,14 @@ Placeholders in this report allow dynamic insertion of values from the datasets.
 <div class='figure-container'>
 
       <div class="subfigure-container active" data-subfigure="1">
-        <div class='export-container'>
-            <button class="csv-btn">CSV</button>
-            <button class="latex-btn">LaTeX</button>
-        </div>
         <div>
             <div>FIGURE</div>
             <script></script>
         </div>
+        <div class='export-container'>
+            <button class="csv-btn">CSV</button>
+            <button class="latex-btn">LaTeX</button>
+        </div>
     </div>
 </div>
 
@@ -124,14 +124,14 @@ Placeholders in this report allow dynamic insertion of values from the datasets.
 <div class='figure-container'>
 
       <div class="subfigure-container active" data-subfigure="1">
-        <div class='export-container'>
-            <button class="csv-btn">CSV</button>
-            <button class="latex-btn">LaTeX</button>
-        </div>
         <div>
             <div>FIGURE</div>
             <script></script>
         </div>
+        <div class='export-container'>
+            <button class="csv-btn">CSV</button>
+            <button class="latex-btn">LaTeX</button>
+        </div>
     </div>
 </div>
 
diff --git a/src/feelpp/benchmarking/json_report/tests/data/golden/table_features.adoc b/src/feelpp/benchmarking/json_report/tests/data/golden/table_features.adoc
index 034eb6221..c70e2a35c 100644
--- a/src/feelpp/benchmarking/json_report/tests/data/golden/table_features.adoc
+++ b/src/feelpp/benchmarking/json_report/tests/data/golden/table_features.adoc
@@ -1,4 +1,4 @@
-:example-caption: Plot
+:example-caption: Figure
 :docdatetime: <TIMESTAMP>
 
 == Student Performance

From 6ba4cadb686a82901bd807a601296bd1f625224f Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Fri, 23 Jan 2026 13:51:13 +0100
Subject: [PATCH 14/16] fix api doc and add section on how to use referencing

---
 .../pages/json_schema/content/figure.adoc     |  2 +
 .../pages/json_schema/content/grid.adoc       |  4 +-
 .../pages/json_schema/content/image.adoc      |  2 +
 .../pages/json_schema/content/latex.adoc      |  2 +
 .../pages/json_schema/content/list.adoc       |  1 +
 .../pages/json_schema/content/section.adoc    |  1 +
 .../pages/json_schema/content/table.adoc      |  2 +
 .../pages/json_schema/content/text.adoc       |  1 +
 .../pages/json_schema/referencing.adoc        | 82 +++++++++++++++++++
 .../pages/json_schema/report_schema.adoc      |  6 +-
 10 files changed, 100 insertions(+), 3 deletions(-)
 create mode 100644 docs/modules/json_report/pages/json_schema/referencing.adoc

diff --git a/docs/modules/json_report/pages/json_schema/content/figure.adoc b/docs/modules/json_report/pages/json_schema/content/figure.adoc
index 4a684d344..ff85915c7 100644
--- a/docs/modules/json_report/pages/json_schema/content/figure.adoc
+++ b/docs/modules/json_report/pages/json_schema/content/figure.adoc
@@ -10,7 +10,9 @@ The **Plot Node** defines a data visualization within the report. It specifies t
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the plot node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"plot"`.|`"plot"`
+|`caption`|string|*Optional.* A descriptive caption for the figure.|`null`
 |`ref`|string|The unique `name`  of the data file (from the root `data` list) to reference for building the figure.|*Required*
 |`plot`|object|The nested configuration object (`Plot` schema) defining the figure's dimensions, type, and transformation.|*Required*
 |===
diff --git a/docs/modules/json_report/pages/json_schema/content/grid.adoc b/docs/modules/json_report/pages/json_schema/content/grid.adoc
index 27ea11aa8..2cef35996 100644
--- a/docs/modules/json_report/pages/json_schema/content/grid.adoc
+++ b/docs/modules/json_report/pages/json_schema/content/grid.adoc
@@ -1,11 +1,13 @@
 = Grid Node
 
-The **Grid Node** is a layout node that can be used to structure content into a grid.
+The **Grid Node** is a layout node that can be used to structure content into a grid. Mainly used to arrange images, plots, or tables side by side in a visually appealing manner. Sub figures or sub plots can be created using this node, but numbering and labeling must be handled manually within the captions of the child nodes.
 
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the grid node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"grid"`.|`"grid"`
+|`caption`|string|*Optional.* A descriptive caption for the grid.|`null`
 |`contents`|array of objects| A list of other (non-recursive) content nodes.|[]
 |columns|int| Number of columns for the grid. Must be between 1 and 4.| 1
 |gap|int| Must be beween 1 and 3| 2.
diff --git a/docs/modules/json_report/pages/json_schema/content/image.adoc b/docs/modules/json_report/pages/json_schema/content/image.adoc
index e2bb8f84d..ec20829b2 100644
--- a/docs/modules/json_report/pages/json_schema/content/image.adoc
+++ b/docs/modules/json_report/pages/json_schema/content/image.adoc
@@ -12,7 +12,9 @@ The `src` file path is typically resolved relative to the passed configuration f
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the image node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"image"`.|`"image"`
+|`caption`|string|*Optional.* A descriptive caption for the image.|`null`
 |`src`|string|The file path or URL of the image to embed.|*Required*
 |`caption`|string|An optional caption displayed beneath the image. If provided, the image is rendered using the `title` attribute in AsciiDoc.|`null`
 |`alt`|string|Alternative text for the image, used for accessibility and when the image cannot be displayed.|`null`
diff --git a/docs/modules/json_report/pages/json_schema/content/latex.adoc b/docs/modules/json_report/pages/json_schema/content/latex.adoc
index c3d0eea92..78ae79fd1 100644
--- a/docs/modules/json_report/pages/json_schema/content/latex.adoc
+++ b/docs/modules/json_report/pages/json_schema/content/latex.adoc
@@ -5,6 +5,8 @@ The **LaTeX Node** is designed for the direct embedding of mathematical formulas
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the LaTeX node within the report. Used for internal cross referencing |`null`
+|`is_equation`|boolean|*Optional.* Indicates if the LaTeX content represents a standalone equation. It adds `\begin\{equation\}` and `\end\{equation\}` around the content if true.|`false`
 |`type`|string|Must be set to `"latex"`.|`"latex"`
 |`latex`|string|The raw LaTeX content (e.g., a mathematical equation or a custom LaTeX block).|*Required*
 |`ref`|string|The `name` of the data field to reference for dynamic placeholder resolution.|`null`
diff --git a/docs/modules/json_report/pages/json_schema/content/list.adoc b/docs/modules/json_report/pages/json_schema/content/list.adoc
index e3067e104..de605e914 100644
--- a/docs/modules/json_report/pages/json_schema/content/list.adoc
+++ b/docs/modules/json_report/pages/json_schema/content/list.adoc
@@ -7,6 +7,7 @@ The **List Node** is used to render ordered lists. Its primary strength is that
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the list node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"itemize"`.|`"itemize"`
 |`items`|array of objects/strings|The contents of the list. Each entry can be a simple string, a full `Text Node` object, or a `Text Configuration` object.|*Required*
 |`ref`|string|The `name` of the data field to reference for dynamic placeholder resolution within all list items.|`null`
diff --git a/docs/modules/json_report/pages/json_schema/content/section.adoc b/docs/modules/json_report/pages/json_schema/content/section.adoc
index 609ade1e9..549c22205 100644
--- a/docs/modules/json_report/pages/json_schema/content/section.adoc
+++ b/docs/modules/json_report/pages/json_schema/content/section.adoc
@@ -5,6 +5,7 @@ The **Section Node** is the fundamental building block for structuring your repo
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the section node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"section"`.|`"section"`
 |`title`|string|The title of the section.|*Required*
 |`contents`|array of objects|A recursive list of other content nodes, including nested `SectionNode`s.| []
diff --git a/docs/modules/json_report/pages/json_schema/content/table.adoc b/docs/modules/json_report/pages/json_schema/content/table.adoc
index 5ffd6d3a6..3b82b09a0 100644
--- a/docs/modules/json_report/pages/json_schema/content/table.adoc
+++ b/docs/modules/json_report/pages/json_schema/content/table.adoc
@@ -10,6 +10,8 @@ The structure is composed of the `TableNode` container and the nested `Table` co
 |===
 |Field|Type|Description|Default Value
 
+
+|`id`|string| *Optional.* Identifies the table node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"table"`.|`"table"`
 |`ref`|string|The unique reference of the data file (from the root `data` list) containing the table to be rendered.|*Required*
 |`caption`|string|*Optional.* Table caption.| `null`
diff --git a/docs/modules/json_report/pages/json_schema/content/text.adoc b/docs/modules/json_report/pages/json_schema/content/text.adoc
index 34d543fe4..5cc3de0a9 100644
--- a/docs/modules/json_report/pages/json_schema/content/text.adoc
+++ b/docs/modules/json_report/pages/json_schema/content/text.adoc
@@ -5,6 +5,7 @@ The **Text Node** is used to insert narrative content into your report. It suppo
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the text node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"text"`.|`"text"`
 |`text`|string or object|The text content or a nested `Text` object.|*Required*
 |`ref`|string|The `name` of the data field to reference for dynamic placeholder resolution.|`null`
diff --git a/docs/modules/json_report/pages/json_schema/referencing.adoc b/docs/modules/json_report/pages/json_schema/referencing.adoc
new file mode 100644
index 000000000..f80007b03
--- /dev/null
+++ b/docs/modules/json_report/pages/json_schema/referencing.adoc
@@ -0,0 +1,82 @@
+= Internal Cross References
+
+It is possible to assign an optional unique identifier to any content node within the JSON report schema. This identifier can then be used to create internal cross-references within the report, allowing for easy navigation between different sections or elements.
+
+== Assigning Identifiers
+
+To assign an identifier to a content node, include the `id` field in the node's JSON object. The value of this field should be a unique string that serves as the identifier for that node.
+[source,json]
+----
+{
+  "type": "section",
+  "id": "introduction",
+  "title": "Introduction",
+  "contents": [
+    // Other content nodes
+  ]
+}
+----
+In this example, the section node is assigned the identifier `"introduction"`.
+
+[IMPORTANT]
+Ensure that each id contains only alphanumeric characters, underscores, or hyphens, and does not start with a number. This ensures compatibility with AsciiDoc cross-referencing conventions.
+
+== Figure and Table Numbering
+
+Tables, figures and images are automatically numbered in the order they appear in the report. However, tables will be prefixed with "Table", figures, plots and images will be prefixed with "Figure". This means that automatic numbering will be independent between tables and figures/images.
+
+[IMPORTANT]
+Elements included inside a grid node are NOT automatically numbered. You must manually include numbering in the caption if desired (e.g. "Figure 1a: ..."). The counter for the automatic numbering will not be incremented for these elements.
+
+== Creating Cross-References
+
+To create a cross-reference to a content node with an assigned identifier, use the AsciiDoc cross-referencing syntax. The format is `<<id, Display Text>>`, where `id` is the identifier of the target node, and `Display Text` is the text that will be displayed as the link in the report.
+
+[source,asciidoc]
+----
+See <<introduction, Introduction Section>> for more details.
+----
+
+In this example, the text "Introduction Section" will be a clickable link that navigates to the section with the identifier `"introduction"`.
+
+[TIP]
+For images, figures and tables, it is possible to reference via their caption without the use of an explicit id (though it is discouraged for clarity). To do so, remove any parentheses from the reference, and replace spaces with hyphens. For example, if a table has the caption "Performance Metrics", you can reference it using `<<Performance-Metrics>>`.
+
+[IMPORTANT]
+Ensure that the identifiers used in cross-references match exactly with those assigned to the content nodes, including case sensitivity. Mismatched identifiers will result in broken links in the final report.
+
+== Example
+
+[source,json]
+----
+{
+  "contents": [
+    {
+        "type":"text",
+        "id":"intro_text",
+        "text":"Welcome to the report."
+    },
+    {
+        "type":"section",
+        "id":"data_analysis",
+        "title":"Data Analysis",
+        "contents":[
+            {
+                "type":"table",
+                "id":"results_table",
+                "ref":"results_data",
+                "caption":"Results Overview"
+            },
+            {
+                "type":"text",
+                "text":"Refer to <<intro_text, the introduction>> for context."
+            }
+        ]
+    },
+    {
+        "type":"text",
+        "text":"See <<results_table, the results table>> for detailed metrics."
+    }
+  ]
+}
+----
\ No newline at end of file
diff --git a/docs/modules/json_report/pages/json_schema/report_schema.adoc b/docs/modules/json_report/pages/json_schema/report_schema.adoc
index 2712975c6..f85d9efa3 100644
--- a/docs/modules/json_report/pages/json_schema/report_schema.adoc
+++ b/docs/modules/json_report/pages/json_schema/report_schema.adoc
@@ -58,7 +58,7 @@ include::data.adoc[leveloffset=+1]
 
 include::content/section.adoc[leveloffset=+1]
 
-include::content/section.adoc[leveloffset=+1]
+include::content/grid.adoc[leveloffset=+1]
 
 include::content/text.adoc[leveloffset=+1]
 
@@ -70,4 +70,6 @@ include::content/image.adoc[leveloffset=+1]
 
 include::content/table.adoc[leveloffset=+1]
 
-include::content/figure.adoc[leveloffset=+1]
\ No newline at end of file
+include::content/figure.adoc[leveloffset=+1]
+
+include::referencing.adoc[leveloffset=+1]
\ No newline at end of file

From 88246636caf2ffe1b81de7196c9cab4199b51051 Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Fri, 23 Jan 2026 13:55:07 +0100
Subject: [PATCH 15/16] syntax fix

---
 docs/modules/json_report/pages/json_schema/referencing.adoc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/modules/json_report/pages/json_schema/referencing.adoc b/docs/modules/json_report/pages/json_schema/referencing.adoc
index f80007b03..c9d590204 100644
--- a/docs/modules/json_report/pages/json_schema/referencing.adoc
+++ b/docs/modules/json_report/pages/json_schema/referencing.adoc
@@ -5,6 +5,7 @@ It is possible to assign an optional unique identifier to any content node withi
 == Assigning Identifiers
 
 To assign an identifier to a content node, include the `id` field in the node's JSON object. The value of this field should be a unique string that serves as the identifier for that node.
+
 [source,json]
 ----
 {
@@ -30,7 +31,7 @@ Elements included inside a grid node are NOT automatically numbered. You must ma
 
 == Creating Cross-References
 
-To create a cross-reference to a content node with an assigned identifier, use the AsciiDoc cross-referencing syntax. The format is `<<id, Display Text>>`, where `id` is the identifier of the target node, and `Display Text` is the text that will be displayed as the link in the report.
+To create a cross-reference to a content node with an assigned identifier, use the link:https://docs.asciidoctor.org/asciidoc/latest/macros/xref/#internal-cross-references[AsciiDoc cross-referencing syntax]. The format is `\<<id, Display Text>>`, where `id` is the identifier of the target node, and `Display Text` is the text that will be displayed as the link in the report.
 
 [source,asciidoc]
 ----
@@ -40,7 +41,7 @@ See <<introduction, Introduction Section>> for more details.
 In this example, the text "Introduction Section" will be a clickable link that navigates to the section with the identifier `"introduction"`.
 
 [TIP]
-For images, figures and tables, it is possible to reference via their caption without the use of an explicit id (though it is discouraged for clarity). To do so, remove any parentheses from the reference, and replace spaces with hyphens. For example, if a table has the caption "Performance Metrics", you can reference it using `<<Performance-Metrics>>`.
+For images, figures and tables, it is possible to reference via their caption without the use of an explicit id (though it is discouraged for clarity). To do so, remove any parentheses from the reference, and replace spaces with hyphens. For example, if a table has the caption "Performance Metrics", you can reference it using `\<<Performance-Metrics>>`.
 
 [IMPORTANT]
 Ensure that the identifiers used in cross-references match exactly with those assigned to the content nodes, including case sensitivity. Mismatched identifiers will result in broken links in the final report.

From 45cef392e289549e9a11f61037bc21ae0feab91a Mon Sep 17 00:00:00 2001
From: Javier Cladellas <javiercladellas@gmail.com>
Date: Fri, 23 Jan 2026 14:16:11 +0100
Subject: [PATCH 16/16] fix parameter table

---
 examples/matrixvector/plots.json |  2 +-
 examples/parallelsum/plots.json  | 27 ++++++++-------------------
 examples/sorting/plots.json      |  2 +-
 3 files changed, 10 insertions(+), 21 deletions(-)

diff --git a/examples/matrixvector/plots.json b/examples/matrixvector/plots.json
index 1f3188743..6d98c7ea4 100644
--- a/examples/matrixvector/plots.json
+++ b/examples/matrixvector/plots.json
@@ -46,7 +46,7 @@
             "contents":[
                 {
                     "type":"table",
-                    "ref": "reframe_df",
+                    "ref": "parameter_table",
                     "layout":{
                         "rename":{
                             "testcases.time_total":"Total Time (s)",
diff --git a/examples/parallelsum/plots.json b/examples/parallelsum/plots.json
index e239a4058..016514012 100644
--- a/examples/parallelsum/plots.json
+++ b/examples/parallelsum/plots.json
@@ -47,33 +47,22 @@
             "contents": [
                 {
                     "type": "table",
-                    "ref": "reframe_df",
+                    "ref": "parameter_table",
                     "layout": {
-                        "columns": ["result", "testcases.hashcode", "tasks", "elements", "testcases.time_total"],
-                        "computed_columns":{
-                            "logs_link":"f'link:logs/{row[\"testcases.hashcode\"]}.html[Logs]'"
-                        },
                         "rename": {
                             "testcases.time_total": "Total Time (s)",
                             "testcases.hashcode": "Hash",
                             "result": "",
                             "logs_link":""
                         },
-                        "group_by": { "columns": ["testcases.hashcode"], "agg": "first" },
-                        "format": {
-                            "testcases.time_total": "%.3f",
-                            "tasks":"%.0f",
-                            "elements":"%.0f",
-                            "result": { "pass": "🟢", "fail": "🔴" }
-                        },
-                        "column_order": ["result", "testcases.hashcode", "tasks", "elements", "testcases.time_total","logs_link"],
-                        "style": {
-                            "column_align": { "result": "center" },
-                            "column_width":{ "result":1,"logs_link":1},
-                            "classnames": ["scrollable", "sortable"]
-                        }
+                        "column_order": ["result", "testcases.hashcode", "tasks", "elements", "testcases.time_total","logs_link"]
                     },
-                    "filter": { "placeholder": "Filter testcases..." }
+                    "filter": { "placeholder": "Filter testcases..." },
+                    "style": {
+                        "column_align": { "result": "center" },
+                        "column_width":{ "result":1,"logs_link":1},
+                        "classnames": ["scrollable", "sortable"]
+                    }
                 }
             ]
         },
diff --git a/examples/sorting/plots.json b/examples/sorting/plots.json
index 9e9deb3ed..4fa4cbe99 100644
--- a/examples/sorting/plots.json
+++ b/examples/sorting/plots.json
@@ -47,7 +47,7 @@
             "contents": [
                 {
                     "type": "table",
-                    "ref": "reframe_df",
+                    "ref": "parameter_table",
                     "layout": {
                         "rename": {
                             "testcases.time_total": "Execution Time (s)",