test: support multipage golden tests

Author: alandefreitas

.gitignore

@@ -27,3 +27,5 @@
 /util/danger/node_modules/
 /.roadmap
 /AGENTS.md
+# Ignore hidden OS files under golden fixtures
+test-files/golden-tests/**/.*

docs/modules/ROOT/pages/contribute.adoc

@@ -263,6 +263,13 @@ The fixtures for golden testing are defined in `test-files/golden-tests`, where
 * `<filename>.bad.xml`: The test output file generated when the test fails.
 * `<filename>.yml`: Extra configuration options for this specific file.
 
+Multipage golden tests follow a snapshot-based layout:
+
+* The suite defaults to `multipage: false` in `test-files/golden-tests/mrdocs.yml`; a multipage test must provide a `<stem>.yml` that sets `multipage: true`.
+* Expected output lives under `<stem>.multipage/<format>/...` (one directory per generator); single-page siblings like `<stem>.html`/`.xml` must be absent.
+* The harness skips `.multipage/` directories during discovery and compares generated temp output trees to the snapshot (strict tree + content).
+* Add a short comment in the `.cpp` explaining why multipage is required—use it only when single-page output cannot validate the behavior (e.g., relative asset/link handling).
+
 == Style Guide
 
 This project follows informal formatting conventions established by previous Boost projects.

mrdocs.rnc

@@ -20,11 +20,47 @@ namespace xsi= "http://www.w3.org/2001/XMLSchema-instance"
 
 grammar
 {
-    start = element mrdocs
-    {
-        attribute xsi:noNamespaceSchemaLocation {text}?,
-        Namespace
-    }
+    start = Mrdocs | Tagfile
+
+    Mrdocs =
+        element mrdocs
+        {
+            attribute xsi:noNamespaceSchemaLocation {text}?,
+            Namespace
+        }
+
+    Tagfile =
+        element tagfile
+        {
+            TagCompound+
+        }
+
+    TagCompound =
+        element compound
+        {
+            attribute kind { "namespace" | "class" },
+            element name { text },
+            element filename { text },
+            (TagClass | TagMember)*
+        }
+
+    TagClass =
+        element class
+        {
+            attribute kind { "class" },
+            text
+        }
+
+    TagMember =
+        element member
+        {
+            attribute kind { "function" },
+            element type { text },
+            element name { text },
+            element anchorfile { text },
+            element anchor { text },
+            element arglist { text }
+        }
 
     #---------------------------------------------
 

src/lib/Gen/hbs/HandlebarsGenerator.hpp

@@ -27,6 +27,28 @@ namespace hbs {
 class HandlebarsGenerator
     : public Generator
 {
+public:
+    struct StylesheetRef
+    {
+        /** Absolute path to the source stylesheet on disk (empty for remote). */
+        std::string sourcePath;
+        /** Href or output-relative path written to the HTML. */
+        std::string outputRelative;
+        /** True when the stylesheet is remote and should not be copied. */
+        bool external = false;
+    };
+
+    struct StylesData
+    {
+        std::vector<StylesheetRef> stylesheets;
+        std::vector<std::string> inlineStyles;
+        std::vector<std::string> inlineScripts;
+        bool hasDefaultStyles = false;
+    };
+
+private:
+    Expected<StylesData> prepareStylesheets(Config const& config) const;
+
 public:
     Expected<void>
     build(