@adobe/helix-md2jcr 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.5.0](https://github.com/adobe/helix-md2jcr/compare/v1.4.1...v1.5.0) (2026-06-17)
+
+
+### Features
+
+* **phrasing:** preserve inline HTML tags in text elements ([#217](https://github.com/adobe/helix-md2jcr/issues/217)) ([5f7d274](https://github.com/adobe/helix-md2jcr/commit/5f7d2745005ae0947866fb66989cdb9626cb3e60))
+
 ## [1.4.1](https://github.com/adobe/helix-md2jcr/compare/v1.4.0...v1.4.1) (2026-06-09)
 
 

package/README.md

@@ -114,6 +114,8 @@ console.log(xml);
   cell is routed back to fields, mirroring block options.
 - [Field Hinting](docs/field-hinting.md) — using `<!-- field: name -->` to skip
   ahead within a field group.
+- [Phrasing Content](docs/phrasing.md) — supported inline HTML tags (`sup`, `sub`,
+  `u`, `del`, `strong`, `em`) and how they survive the markdown → JCR pipeline.
 
 ## Baseline XML Files
 Running the ./baseline-tests.sh script will detect any md file under test/fixtures and execute the convert2jcr node script.  

package/docs/phrasing.md

@@ -0,0 +1,54 @@
+# Phrasing Content (Inline HTML)
+
+Phrasing content refers to inline elements that flow within a line of text — as
+opposed to block-level elements like paragraphs, headings, and lists.
+
+When raw HTML inline tags appear in markdown source, remark parses them as `html`
+nodes. The `mdast-sanitize-html` step converts them into typed mdast nodes, and
+the serializer then maps those nodes back to their HTML equivalents when writing
+the `text` attribute of a JCR text component.
+
+## Supported Tags
+
+| HTML tag | mdast node type | Serializes to |
+|---|---|---|
+| `<sup>` | `superscript` | `<sup>` |
+| `<sub>` | `subscript` | `<sub>` |
+| `<u>` | `underline` | `<u>` |
+| `<del>` | `delete` | `<del>` |
+| `<strong>` | `strong` | `<strong>` |
+| `<em>` | `emphasis` | `<em>` |
+
+`superscript`, `subscript`, and `underline` are custom node types introduced by
+`mdast-sanitize-html`. They require explicit handlers in `hast-handlers.js` so
+that `mdast-util-to-hast` knows to emit the correct tag rather than falling back
+to `<div>`. The remaining three (`delete`, `strong`, `emphasis`) are standard
+mdast types with built-in hast handlers.
+
+## Example
+
+Markdown source:
+
+```markdown
+E = mc<sup>2</sup> and H<sub>2</sub>O with <u>underline</u>, <del>strike</del>, <strong>bold</strong>, <em>italic</em>.
+```
+
+Resulting `text` attribute value:
+
+```html
+<p>E = mc<sup>2</sup> and H<sub>2</sub>O with <u>underline</u>, <del>strike</del>, <strong>bold</strong>, <em>italic</em>.</p>
+```
+
+## Pipeline
+
+```
+markdown source
+  → remark parse → html nodes (raw inline HTML)
+  → mdast-sanitize-html → typed mdast nodes (superscript, subscript, etc.)
+  → toHast (with customHastHandlers) → hast element nodes
+  → toHtml → HTML string stored in JCR text attribute
+```
+
+The custom handlers live in
+`src/mdast2jcr/hb/partials/supports/hast-handlers.js` and are applied wherever
+`toHast` is called — currently `paragraph.js` and `grid-table.js`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-md2jcr",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Helix Service that converts markdown to JCR content structure",
   "main": "src/index.js",
   "type": "module",

package/src/mdast2jcr/hb/partials/grid-table.js

@@ -16,6 +16,7 @@ import { toString } from 'mdast-util-to-string';
 import Handlebars from 'handlebars';
 import { toHast } from 'mdast-util-to-hast';
 import { toHtml } from 'hast-util-to-html';
+import { customHastHandlers } from './supports/hast-handlers.js';
 import { getComponentById, getComponentByTitle, getModelId } from '../../domain/Definitions.js';
 import {
   findModelById,
@@ -177,6 +178,7 @@ function extractPropertiesForNode(field, currentNode, properties) {
       value = currentNode.children.reduce((acc, node) => {
         const hast = toHast(node, {
           allowDangerousHtml: true,
+          handlers: customHastHandlers,
         });
 
         let str = toHtml(hast, {
@@ -190,7 +192,7 @@ function extractPropertiesForNode(field, currentNode, properties) {
         return acc + encodeHtml(str);
       }, '');
     } else {
-      value = encodeHtml(toHtml(toHast(currentNode)));
+      value = encodeHtml(toHtml(toHast(currentNode, { handlers: customHastHandlers })));
     }
 
     // if the node is a code block then don't strip out the newlines

package/src/mdast2jcr/hb/partials/paragraph.js

@@ -13,10 +13,11 @@ import Handlebars from 'handlebars';
 
 import { toHast } from 'mdast-util-to-hast';
 import { toHtml } from 'hast-util-to-html';
+import { customHastHandlers } from './supports/hast-handlers.js';
 
 function paragraph(context) {
   const html = context.children.map((child) => {
-    const hast = toHast(child);
+    const hast = toHast(child, { handlers: customHastHandlers });
     return toHtml(hast);
   }).join('');
 

package/src/mdast2jcr/hb/partials/supports/hast-handlers.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * Creates a hast handler that maps a custom mdast node type to an inline HTML element.
+ * mdast-util-to-hast has no built-in knowledge of superscript/subscript/underline nodes
+ * (introduced by mdast-sanitize-html), so without these handlers those nodes fall back
+ * to <div>, losing the semantic tag.
+ *
+ * @param {string} tagName - HTML tag to emit (e.g. 'sup', 'sub', 'u')
+ * @returns {function(State, Node): Element} hast handler
+ */
+function formatHandler(tagName) {
+  return (state, node) => ({
+    type: 'element',
+    tagName,
+    properties: {},
+    children: state.all(node),
+  });
+}
+
+/**
+ * Custom hast handlers for mdast node types that mdast-util-to-hast does not recognize
+ * by default. Pass these as the `handlers` option wherever toHast() is called so that
+ * inline formatting round-trips correctly through the mdast → hast → HTML pipeline.
+ */
+export const customHastHandlers = {
+  superscript: formatHandler('sup'),
+  subscript: formatHandler('sub'),
+  underline: formatHandler('u'),
+};