@adobe/helix-md2jcr

Helix Markdown to JCR

A library that converts markdown to JCR.

Status

Development

Install all dependencies by running:

npm install

Usage

Installation

You can install the package via npm:

npm install @adobe/helix-md2jcr

Or use it directly with npx without installing:

npx @adobe/helix-md2jcr path/to/content.md

Converting Markdown to JCR Nodes

The package includes a CLI tool md2jcr that converts markdown files to JCR XML format.

Basic usage:

npx @adobe/helix-md2jcr path/to/content.md

Convert a single file:

md2jcr test/fixtures/simple.md

Convert all markdown files in a directory:

md2jcr test/fixtures/

View output in console with verbose flag -v:

md2jcr test/fixtures/simple.md -v

View decoded XML output with -v and -d flags:

md2jcr test/fixtures/simple.md -v -d

Use custom Universal Editor files from a directory:

md2jcr content.md -ue path/to/ue-files-directory

The converter will generate a .xml file alongside the markdown file containing the JCR structure. This can be used to check for potential content changes due to conversion.

Command-Line Options

• -v, --verbose - Print the XML output to the console
• -d, --decode - Decode HTML entities in the XML output (use with -v)
• -ue, --ue-files <directory> - Specify a directory containing Universal Editor configuration files

Example directory structure:

ue-files/
  ├── component-models.json
  ├── component-definition.json
  └── component-filters.json

Programmatic Usage

You can also use the library programmatically in your Node.js code:

import { md2jcr } from '@adobe/helix-md2jcr';

const markdown = '# Hello World\n\nThis is a test.';
const options = {
  models: [...],
  definition: {...},
  filters: [...]
};

const xml = await md2jcr(markdown, options);
console.log(xml);

Documentation

• Container Blocks — how container blocks map parent properties and child items (the one-column / many-column rules, omitting parent rows, and error cases). See also the container-block test fixtures for a worked scenario-by-scenario breakdown.
• Block Options (Classes) — block option classes and element grouping (classes, classes_*): how header options are routed to fields by their options or boolean name-suffix.
• Section Styles — element grouping for a section's style group (style, style_*): how the single Section Metadata style cell is routed back to fields, mirroring block options.
• Field Hinting — using <!-- field: name --> to skip ahead within a field group.
• Phrasing Content — 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.
The script will generate new xml files beside the md files it locates. This is helpful when making changes to the converter and you want to see if the changes have any impact on the output. By using git diff, you will see the new changes in the xml files. If you are satisfied with the changes, you can commit the new xml files.

Running Tests

Simply execute the following command to run the tests:

npm test