Error: MDX compilation failed on docify generated output

[jimthompson5802]

Bug Report

Steps to Reproduce:

1. Created a simple two node architecture with a connects relationship. The relationship has a metadata field called "operations" with a list of four string values. File is called simple.architecture.json.

{
    "$schema": "https://calm.finos.org/release/1.1/meta/calm.json",
    "unique-id": "simple-architecture",
    "name": "Simple Architecture",
    "description": "A minimal CALM architecture example",
    "nodes": [
        {
            "unique-id": "system-a",
            "node-type": "system",
            "name": "System A",
            "description": "First system in the architecture"
        },
        {
            "unique-id": "system-b",
            "node-type": "system",
            "name": "System B",
            "description": "Second system in the architecture"
        }
    ],
    "relationships": [
        {
            "unique-id": "system-a-connects-to-system-b",
            "relationship-type": {
                "connects": {
                    "source": {
                        "node": "system-a"
                    },
                    "destination": {
                        "node": "system-b"
                    }
                }
            },
            "description": "System A connects to System B",
            "metadata": {
                "operations": ["add", "substract", "multiply", "divide"]
            }
        }
    ]
}

3. run calm validate -a /Users/jim/Desktop/calm-demos/traderX_testbed/simple.architecture.json No warnings or errors are generated.
4. run calm docify -a /Users/jim/Desktop/calm-demos/traderX_testbed/simple.architecture.json -o /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html --clear-output-directory Web content files are generated.
5. cd simple-docs/html
6. run npm install
7. run npm start

Expected Result:

Should have created static web content in simple-docs/html that is viewable with a broswer.

Actual Result:

During execution of npm start, encountered this error

Mac:jim html[503]$ npm start

> arch-docs@1.0.0 start
> docusaurus start

[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/

✖ Client
  Compiled with some errors in 11.76s

Error: MDX compilation failed for file "/Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/docs/relationships/system-a-connects-to-system-b.md"
Cause: Expected a closing tag for `<td>` (48:13-48:17) before the end of `paragraph`
Details:
{
  "column": 13,
  "file": "",
  "message": "Expected a closing tag for `<td>` (48:13-48:17) before the end of `paragraph`",
  "line": 47,
  "name": "47:13-51:23",
  "place": {
    "start": {
      "_bufferIndex": 0,
      "_index": 0,
      "line": 47,
      "column": 13,
      "offset": 896
    },
    "end": {
      "_bufferIndex": -1,
      "_index": 9,
      "line": 51,
      "column": 23,
      "offset": 1009
    }
  },
  "reason": "Expected a closing tag for `<td>` (48:13-48:17) before the end of `paragraph`",
  "ruleId": "end-tag-mismatch",
  "source": "mdast-util-mdx-jsx"
}
client (webpack 5.104.1) compiled with 1 error
<w> [webpack.cache.PackFileCacheStrategy] Skipped not serializable cache item 'Compilation/modules|/Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/node_modules/@docusaurus/mdx-loader/lib/index.js??ruleSet[1].rules[8].use[0]!/Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/docs/relationships/system-a-connects-to-system-b.md': No serializer registered for VFileMessage
<w> while serializing webpack/lib/cache/PackFileCacheStrategy.PackContentItems -> webpack/lib/NormalModule -> webpack/lib/ModuleBuildError -> Error -> VFileMessage
       

Environment:

OS: MacOS Sequoia 15.7.3
Hardware: MacBookPro: Apple M4, 48GB RAM
CALM VERSION: calm-cli: 1.29.0

Additional Context:

From what I can tell, the issue is in the generated file for the relationship system-a-connects-to-system-between.md The issue is the newlines embedded between the <td> and </td> for the "operations" metadata.

## Metadata
<div class="table-container">
    <table>
        <thead>
        <tr>
            <th>Key</th>
            <th>Value</th>
        </tr>
        </thead>
        <tbody>
        <tr>
            <th>Operations</th>
            <td>add
                substract
                multiply
                divide
                </td>
        </tr>
        </tbody>
    </table>
</div>

If I modify that section to be
<td>add, substract, multiply, divde</td> the compilation error does not occur and I can view the architecture with a web browser

Full log output

Mac:jim traderX_testbed[501]$  calm validate -a /Users/jim/Desktop/calm-demos/traderX_testbed/simple.architecture.json
info [file-system-document-loader]:     /Users/jim/Desktop/calm-demos/traderX_testbed/simple.architecture.json exists, loading as file...
info [calm-validate]:     Formatting output as json
{
    "jsonSchemaValidationOutputs": [],
    "spectralSchemaValidationOutputs": [],
    "hasErrors": false,
    "hasWarnings": false
}Mac:jim traderX_testbed[501]$  calm docify -a /Users/jim/Desktop/calm-demos/traderX_testbed/simple.architecture.json -o /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html --clear-output-directory
info [_TemplateProcessor]:     Using TemplateBundleFileLoader for bundle
info [_TemplateBundleFileLoader]:     📥 Loading index.json from /Users/jim/.nvm/versions/node/v24.4.1/lib/node_modules/@finos/calm-cli/dist/template-bundles/docusaurus/index.json
info [_TemplateBundleFileLoader]:     ✅ Successfully loaded template bundle: docusaurus-v2-docs
info [_TemplateBundleFileLoader]:     📂 Loading template files from: /Users/jim/.nvm/versions/node/v24.4.1/lib/node_modules/@finos/calm-cli/dist/template-bundles/docusaurus
info [_TemplateBundleFileLoader]:     🎯 Total Templates Loaded: 10
[WidgetEngine] ⚠️ Helper 'lookup' is already registered. Skipping registration.
info [_TemplateProcessor]:     📂 Creating output directory: /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html
info [_TemplateProcessor]:     ℹ️ No transformer specified in index.json. Will use TemplateDefaultTransformer.
info [_TemplateProcessor]:     🔁 No transformer provided. Using TemplateDefaultTransformer.
info [_TemplateEngine]:     ✅ Compiled 10 Templates
info [_TemplateEngine]:     🔧 Registering Handlebars Helpers...
info [_TemplateEngine]:     ✅ Registered helper: eq
info [_TemplateEngine]:     ✅ Registered helper: lookup
info [_TemplateEngine]:     ✅ Registered helper: json
info [_TemplateEngine]:     ✅ Registered helper: instanceOf
info [_TemplateEngine]:     ✅ Registered helper: kebabToTitleCase
info [_TemplateEngine]:     ✅ Registered helper: kebabCase
info [_TemplateEngine]:     ✅ Registered helper: isObject
info [_TemplateEngine]:     ✅ Registered helper: isArray
info [_TemplateEngine]:     ✅ Registered helper: join
info [_TemplateEngine]:     
🔹 Starting Template Generation...
info [_TemplateEngine]:     ✅ Generated: /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/docs/nodes/system-a.md
info [_TemplateEngine]:     ✅ Generated: /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/docs/nodes/system-b.md
info [_TemplateEngine]:     ✅ Generated: /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/docs/relationships/system-a-connects-to-system-b.md
warn [_TemplateEngine]:     ⚠️ Expected array for repeated output, but found non-array for flow.mdx.hbs
info [_TemplateEngine]:     ✅ Generated: /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/docs/index.md
info [_TemplateEngine]:     ✅ Generated: /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/sidebars.js
info [_TemplateEngine]:     📋 Copied: /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/docusaurus.config.js
info [_TemplateEngine]:     📋 Copied: /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/package.json
info [_TemplateEngine]:     📋 Copied: /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/static/img/2025_CALM_Icon.svg
info [_TemplateEngine]:     📋 Copied: /Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/static/css/custom.css
info [_TemplateEngine]:     
✅ Template Generation Completed!
info [_TemplateProcessor]:     
✅ Template Generation Completed!
Mac:jim traderX_testbed[501]$ cd simple-docs/html
Mac:jim html[502]$ npm install
npm warn deprecated whatwg-encoding@3.1.1: Use @exodus/bytes instead for a more spec-conformant and faster implementation
npm warn deprecated acorn-dynamic-import@4.0.0: This is probably built in to whatever tool you're using. If you still need it... idk
npm warn deprecated sourcemap-codec@1.4.8: Please use @jridgewell/sourcemap-codec instead

added 1465 packages, and audited 1466 packages in 13s

432 packages are looking for funding
  run `npm fund` for details

8 moderate severity vulnerabilities

To address all issues, run:
  npm audit fix

Run `npm audit` for details.
Mac:jim html[503]$ npm start

> arch-docs@1.0.0 start
> docusaurus start

[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/

✖ Client
  Compiled with some errors in 11.76s

Error: MDX compilation failed for file "/Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/docs/relationships/system-a-connects-to-system-b.md"
Cause: Expected a closing tag for `<td>` (48:13-48:17) before the end of `paragraph`
Details:
{
  "column": 13,
  "file": "",
  "message": "Expected a closing tag for `<td>` (48:13-48:17) before the end of `paragraph`",
  "line": 47,
  "name": "47:13-51:23",
  "place": {
    "start": {
      "_bufferIndex": 0,
      "_index": 0,
      "line": 47,
      "column": 13,
      "offset": 896
    },
    "end": {
      "_bufferIndex": -1,
      "_index": 9,
      "line": 51,
      "column": 23,
      "offset": 1009
    }
  },
  "reason": "Expected a closing tag for `<td>` (48:13-48:17) before the end of `paragraph`",
  "ruleId": "end-tag-mismatch",
  "source": "mdast-util-mdx-jsx"
}
client (webpack 5.104.1) compiled with 1 error
<w> [webpack.cache.PackFileCacheStrategy] Skipped not serializable cache item 'Compilation/modules|/Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/node_modules/@docusaurus/mdx-loader/lib/index.js??ruleSet[1].rules[8].use[0]!/Users/jim/Desktop/calm-demos/traderX_testbed/simple-docs/html/docs/relationships/system-a-connects-to-system-b.md': No serializer registered for VFileMessage
<w> while serializing webpack/lib/cache/PackFileCacheStrategy.PackContentItems -> webpack/lib/NormalModule -> webpack/lib/ModuleBuildError -> Error -> VFileMessage

[LeighFinegold]

Hi @jimthompson5802 thanks for raising.

The relationship page template delegates metadata rendering to the table widget:

## Metadata
{{table _architecture.relationships["{{relationship-id}}"].metadata orientation="vertical" empty-message="No metadata defined."}}

Template reference: https://github.com/finos/architecture-as-code/blob/main/shared/src/docify/template-bundles/docusaurus/relationship.mdx.hbs#L26-L27

This uses the table widget in vertical mode.

Based on the change history, this behavior was introduced in #1976, which added support for rendering nested objects and arrays in vertical table cells.

Specifically, when metadata contains an array of primitive values (e.g., "operations": ["add", "subtract", "multiply", "divide"]), the template iterates over the array and emits each value on a separate line:

<td>add
    subtract
    multiply
    divide
</td>

MDX interprets newlines inside HTML tags as paragraph breaks, causing the compilation error:

Expected a closing tag for `<td>` before the end of `paragraph`

Root Cause

In calm-widgets/src/widgets/table/table-vertical.html, the array iteration outputs primitive values with embedded newlines between them rather than joining them inline.

The relevant code:

{{else if (isArray cellValue)}}{{#each cellValue}}{{#if (isObject this)}}
{{> table-template.html ...}}
{{else}}{{this}}
{{/if}}{{/each}}

The {{else}}{{this}} followed by newline causes the issue.

Proposed Fix

Render primitive array values inline with a comma separator using Handlebars @last variable:

{{else}}{{this}}{{#unless @last}}, {{/unless}}{{/if}}

This produces: <td>add, subtract, multiply, divide</td>

The same fix should be applied to row-template.html for consistency in horizontal tables.

Files to Update

• calm-widgets/src/widgets/table/table-vertical.html
• calm-widgets/src/widgets/table/row-template.html

Test Fixture

Add a new test fixture at calm-widgets/test-fixtures/table-widget/metadata-primitive-array/ to verify MDX-safe rendering of primitive arrays.

@jimthompson5802 - you want to have a go as a contribution to calm-widgets? otherwise I raise a PR with the fix.

[jimthompson5802]

@LeighFinegold You do the fix. I have some day-job tasks to catch up on.