docs: replace the manual DOM reference with a generated one

This replaces the hand-written DOM reference with one generated from
mrdocs-dom-schema.json. A new Antora extension walks the file's `$defs`
in source order and emits one section per type.

Author: gennaroprota

docs/antora-playbook.yml

@@ -54,3 +54,4 @@ asciidoc:
     - ./extensions/mrdocs-demos.js
     - ./extensions/mrdocs-releases.js
     - ./extensions/config-options-reference.js
+    - ./extensions/dom-reference.js

docs/extensions/dom-reference.js

@@ -0,0 +1,165 @@
+/*
+    Copyright (c) 2026 Gennaro Prota (gennaro.prota@gmail.com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+    Official repository: https://github.com/cppalliance/mrdocs
+
+    Antora extension that renders the DOM Reference section of the
+    docs site from mrdocs-dom-schema.json. Drop-in counterpart to
+    config-options-reference.js for the JSON-Schema describing the
+    Handlebars DOM.
+*/
+
+function escapeHtml(str)
+{
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#039;");
+}
+
+// Convert a CamelCase / PascalCase type name into a kebab-case
+// anchor id. Adjacent uppercase letters that look like an acronym
+// (e.g. "TParam", "TArg") stay glued together - the existing
+// manually-maintained docs use `tparam-fields` and `targ-fields`,
+// not `t-param-fields` / `t-arg-fields`, and we preserve that.
+function kebabAnchor(name)
+{
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .toLowerCase();
+}
+
+function anchorFor(typeName)
+{
+    return kebabAnchor(typeName) + '-fields';
+}
+
+// Strip "#/$defs/X" -> "X".
+function refTypeName(ref)
+{
+    const prefix = '#/$defs/';
+    return ref.startsWith(prefix) ? ref.substring(prefix.length) : ref;
+}
+
+// Render the type cell of a property. Returns HTML.
+function describeType(prop)
+{
+    if (prop.$ref) {
+        const t = refTypeName(prop.$ref);
+        return `<a href="#${anchorFor(t)}"><code>${t}</code></a>`;
+    }
+    if (prop.const !== undefined) {
+        return `<code>"${escapeHtml(String(prop.const))}"</code>`;
+    }
+    if (prop.type === 'array') {
+        return `array of ${describeType(prop.items)}`;
+    }
+    if (prop.type === 'string' && Array.isArray(prop.enum)) {
+        const values = prop.enum.map(v =>
+            `<code>"${escapeHtml(v)}"</code>`).join(' &#124; ');
+        return `string (${values})`;
+    }
+    if (prop.type === 'object') {
+        return 'object';
+    }
+    return prop.type || 'any';
+}
+
+// Render one `$defs` entry: heading + description + members table
+// (or a `oneOf` list, for polymorphic unions).
+function renderTypeSection(typeName, schema, level, block)
+{
+    block.lines.push(
+        `<div class="sect${level - 1}">`);
+    block.lines.push(
+        `<h${level} id="${anchorFor(typeName)}">`);
+    block.lines.push(
+        `<a class="anchor" href="#${anchorFor(typeName)}"></a>`);
+    block.lines.push(escapeHtml(typeName));
+    block.lines.push(`</h${level}>`);
+    block.lines.push(`<div class="sectionbody">`);
+
+    if (schema.description) {
+        block.lines.push(
+            `<div class="paragraph"><p>${escapeHtml(schema.description)}</p></div>`);
+    }
+
+    if (Array.isArray(schema.oneOf)) {
+        // Polymorphic union: list each variant as a link.
+        block.lines.push(`<div class="paragraph"><p>One of:</p></div>`);
+        block.lines.push(`<div class="ulist"><ul>`);
+        for (const variant of schema.oneOf) {
+            const name = refTypeName(variant.$ref);
+            block.lines.push(
+                `<li><a href="#${anchorFor(name)}"><code>${escapeHtml(name)}</code></a></li>`);
+        }
+        block.lines.push(`</ul></div>`);
+    } else if (schema.properties) {
+        // Object type: render the property table.
+        const required = new Set(schema.required || []);
+        block.lines.push(
+            `<table class="tableblock frame-all grid-all stretch">`);
+        block.lines.push(`<colgroup>`);
+        block.lines.push(`<col style="width: 25%;">`);
+        block.lines.push(`<col style="width: 25%;">`);
+        block.lines.push(`<col style="width: 50%;">`);
+        block.lines.push(`</colgroup>`);
+        block.lines.push(`<thead><tr>`);
+        block.lines.push(
+            `<th class="tableblock halign-left valign-top">Property</th>`);
+        block.lines.push(
+            `<th class="tableblock halign-left valign-top">Type</th>`);
+        block.lines.push(
+            `<th class="tableblock halign-left valign-top">Description</th>`);
+        block.lines.push(`</tr></thead>`);
+        block.lines.push(`<tbody>`);
+        for (const [name, prop] of Object.entries(schema.properties)) {
+            block.lines.push(`<tr>`);
+            block.lines.push(
+                `<td class="tableblock halign-left valign-top">`
+                + `<code>${escapeHtml(name)}</code>`
+                + (required.has(name)
+                    ? ` <span style="color: orangered;">(required)</span>`
+                    : '')
+                + `</td>`);
+            block.lines.push(
+                `<td class="tableblock halign-left valign-top">${describeType(prop)}</td>`);
+            block.lines.push(
+                `<td class="tableblock halign-left valign-top">`
+                + (prop.description ? escapeHtml(prop.description) : '')
+                + `</td>`);
+            block.lines.push(`</tr>`);
+        }
+        block.lines.push(`</tbody>`);
+        block.lines.push(`</table>`);
+    }
+
+    block.lines.push(`</div>`); // sectionbody
+    block.lines.push(`</div>`); // sect
+}
+
+module.exports = function (registry) {
+    if (!registry) {
+        throw new Error('registry must be defined');
+    }
+    registry.block('dom-reference', function () {
+        const self = this;
+        self.onContext('example');
+        self.process((parent, reader, attrs) => {
+            const level = parseInt(attrs.level || 3, 10);
+            const code = reader.getLines().join('\n');
+            const schema = JSON.parse(code);
+            const block = self.$create_pass_block(parent, '', Opal.hash(attrs));
+            const defs = schema['$defs'] || {};
+            for (const [typeName, def] of Object.entries(defs)) {
+                renderTypeSection(typeName, def, level, block);
+            }
+            return block;
+        });
+    });
+};