@adobe/helix-md2jcr 1.1.38 → 1.2.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [1.2.1](https://github.com/adobe/helix-md2jcr/compare/v1.2.0...v1.2.1) (2025-10-06)
+
+
+### Bug Fixes
+
+* cli specify the folder to look for the json files in ([b7664fe](https://github.com/adobe/helix-md2jcr/commit/b7664fe1b5a8781218e8585649cb1d0bc099cdbc))
+
+# [1.2.0](https://github.com/adobe/helix-md2jcr/compare/v1.1.38...v1.2.0) (2025-10-06)
+
+
+### Features
+
+* add global CLI command for md2jcr ([4705024](https://github.com/adobe/helix-md2jcr/commit/47050246625b58ea93d23ac8c7fc303edc81998f))
+
 ## [1.1.38](https://github.com/adobe/helix-md2jcr/compare/v1.1.37...v1.1.38) (2025-10-06)
 
 

package/README.md

@@ -16,31 +16,88 @@ npm install
 ```
 
 ## Usage
+
+### Installation
+
 You can install the package via npm:
 
 ```bash
 npm install @adobe/helix-md2jcr
 ```
 
-## Converting Markdown to JCR Nodes
-Running the following command will generate an XML file with the JCR structure alongside of the input file.
+Or use it directly with `npx` without installing:
+
+```bash
+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:**
+```bash
+npx @adobe/helix-md2jcr path/to/content.md
+```
+
+**Convert a single file:**
+```bash
+md2jcr test/fixtures/simple.md
+```
+
+**Convert all markdown files in a directory:**
+```bash
+md2jcr test/fixtures/
+```
 
-For example generating xml for the simple.md file, run:
+**View output in console with verbose flag `-v`:**
 ```bash
-node ./src/cli/convert2jcr.js test/fixtures/simple.md 
+md2jcr test/fixtures/simple.md -v
 ```
-If you wish to see the output in the console, you can run the following command with the verbose flag -v
+
+**View decoded XML output with `-v` and `-d` flags:**
 ```bash
-node ./src/cli/convert2jcr.js test/fixtures/simple.md -v
+md2jcr test/fixtures/simple.md -v -d
 ```
 
-If you wish to see the decoded output in the console you can run the following command with the verbose and decode flags -v and -d:
+**Use custom Universal Editor files from a directory:**
 ```bash
-node ./src/cli/convert2jcr.js test/fixtures/simple.md -v -d
+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
 ```
 
-The converter will produce a `.xml` which is the generated document converted
-from markdown. This can be used to check for potential content changes due to conversion.
+### Programmatic Usage
+
+You can also use the library programmatically in your Node.js code:
+
+```javascript
+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);
+```
 
 ## Baseline XML Files
 Running the ./baseline-tests.sh script will detect any md file under test/fixtures and execute the convert2jcr node script.  

package/baseline-tests.sh

@@ -36,7 +36,7 @@ done
 MD_DIR="test/fixtures"
 
 # Node script to execute
-NODE_SCRIPT="src/cli/convert2jcr.js"
+NODE_SCRIPT="bin/md2jcr.js"
 
 # Check if the directory exists
 if [ ! -d "$MD_DIR" ]; then

package/bin/md2jcr.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+
+/*
+ * Copyright 2024 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.
+ */
+
+/* eslint-disable no-await-in-loop,no-console */
+import {
+  readdir, readFile, stat, writeFile,
+} from 'fs/promises';
+import path from 'path';
+import { decode } from 'entities';
+import { md2jcr } from '../src/index.js';
+
+/**
+ * Read a JSON file. If the file does not exist, return an empty object.
+ * @param {string} filePath The path to the JSON file.
+ * @returns {Promise<{}|any>} A promise that resolves to the JSON object in the file,
+ */
+async function readJsonFile(filePath) {
+  try {
+    if ((await stat(filePath)).isFile()) {
+      const models = await readFile(filePath, 'utf-8');
+      return JSON.parse(models);
+    }
+  } catch (error) {
+    // ignore the fact that the file doesn't exist
+    // console.error(`Error due to: ${error} for file ${filePath}`);
+  }
+  return {};
+}
+
+/**
+ * Convert a markdown file to JCR XML.
+ * @param mdFile {string} The path to the markdown file.
+ * @param verbose - if true the XML will be printed to the console.
+ * @param decodeXML - if true a file with the decoded XML will be created.
+ * @param ueFilesDir - optional path to directory containing UE files (models, definitions, filters)
+ * @returns {Promise<void>} A promise that resolves when the conversion is
+ * complete, or rejects if the file is not a markdown file.
+ */
+async function convert(
+  mdFile,
+  verbose = false,
+  decodeXML = false,
+  ueFilesDir = null,
+) {
+  if (!mdFile.endsWith('.md')) {
+    return Promise.reject(new Error('File must be a markdown file'));
+  }
+
+  const dir = path.dirname(mdFile);
+  const base = path.basename(mdFile, '.md');
+  const fileJcrXML = path.resolve(dir, `${base}.xml`);
+
+  let modelJson;
+  let definitionJson;
+  let filtersJson;
+
+  // Use provided UE files directory if specified
+  if (ueFilesDir) {
+    const ueDir = path.resolve(process.cwd(), ueFilesDir);
+
+    // Try to load models.json
+    const modelsPath = path.resolve(ueDir, 'component-models.json');
+    const loadedModels = await readJsonFile(modelsPath);
+    modelJson = Array.isArray(loadedModels) ? loadedModels : loadedModels.models;
+
+    // Try to load definitions.json
+    const definitionsPath = path.resolve(ueDir, 'component-definition.json');
+    const loadedDefinitions = await readJsonFile(definitionsPath);
+    if (loadedDefinitions.groups) {
+      definitionJson = loadedDefinitions;
+    } else if (loadedDefinitions.definitions) {
+      // Wrap definitions in the expected structure
+      definitionJson = {
+        groups: [
+          {
+            title: 'Blocks',
+            id: 'blocks',
+            components: loadedDefinitions.definitions,
+          },
+        ],
+      };
+    } else {
+      definitionJson = loadedDefinitions;
+    }
+
+    // Try to load filters.json
+    const filtersPath = path.resolve(ueDir, 'component-filters.json');
+    const loadedFilters = await readJsonFile(filtersPath);
+    filtersJson = Array.isArray(loadedFilters) ? loadedFilters : loadedFilters.filters;
+  } else {
+    // Fall back to automatic discovery
+    const blockDefinitionsPath = path.resolve(dir, `_${base}.json`);
+
+    // check to see if the blockFiles exists
+    try {
+      await stat(blockDefinitionsPath);
+      const blockDefinitionFile = await readJsonFile(path.resolve(dir, `_${base}.json`));
+      modelJson = blockDefinitionFile.models;
+      definitionJson = {
+        groups: [
+          {
+            title: 'Blocks',
+            id: 'blocks',
+            components: [
+              ...blockDefinitionFile.definitions,
+            ],
+          },
+        ],
+      };
+      filtersJson = blockDefinitionFile.filters;
+    } catch (err) {
+      const modelFile = path.resolve(dir, `${base}-models.json`);
+      const definitionFile = path.resolve(dir, `${base}-definitions.json`);
+      const filtersFile = path.resolve(dir, `${base}-filters.json`);
+      modelJson = await readJsonFile(modelFile);
+      definitionJson = await readJsonFile(definitionFile);
+      filtersJson = await readJsonFile(filtersFile);
+    }
+  }
+
+  const md = await readFile(mdFile, 'utf-8');
+
+  /** @type {Mdast2JCROptions} */
+  const opts = {
+    models: modelJson,
+    definition: definitionJson,
+    filters: filtersJson,
+  };
+
+  const xml = await md2jcr(md, opts);
+
+  if (verbose) {
+    if (!decodeXML) {
+      console.log(xml);
+    } else if (decodeXML) {
+      console.log(decode(xml));
+    }
+  }
+
+  return writeFile(fileJcrXML, xml);
+}
+
+/**
+ * Parse command-line arguments
+ * @returns {object} Parsed arguments
+ */
+function parseArgs() {
+  const args = {
+    path: null,
+    verbose: false,
+    decode: false,
+    ueFilesDir: null,
+  };
+
+  for (let i = 2; i < process.argv.length; i += 1) {
+    const arg = process.argv[i];
+
+    if (arg === '-v' || arg === '--verbose') {
+      args.verbose = true;
+    } else if (arg === '-d' || arg === '--decode') {
+      args.decode = true;
+    } else if (arg === '-ue' || arg === '--ue-files') {
+      args.ueFilesDir = process.argv[i + 1];
+      i += 1;
+    } else if (!arg.startsWith('-')) {
+      args.path = arg;
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Entry point to convert a markdown file to JCR XML.
+ * @param inPath {string} The path to the markdown file or directory containing
+ * markdown files.
+ * @param verbose {boolean} If true, print output to console
+ * @param htmlDecode {boolean} If true, decode HTML entities in output
+ * @param ueFilesDir {string|null} Optional path to directory containing UE files
+ * @returns {Promise<void>} A promise that resolves when the conversion is
+ * complete.
+ */
+export async function run(inPath, verbose, htmlDecode, ueFilesDir) {
+  const dirOrFilePath = path.resolve(process.cwd(), inPath);
+
+  const files = [];
+  if ((await stat(dirOrFilePath)).isDirectory()) {
+    const items = await readdir(dirOrFilePath);
+    items
+      .filter((item) => item.endsWith('.md'))
+      .forEach((item) => files.push(path.resolve(dirOrFilePath, item)));
+  } else {
+    files.push(dirOrFilePath);
+  }
+
+  for (const file of files) {
+    await convert(file, verbose, htmlDecode, ueFilesDir);
+  }
+}
+
+const args = parseArgs();
+
+run(
+  args.path || process.cwd(),
+  args.verbose,
+  args.decode,
+  args.ueFilesDir,
+).catch(console.error);

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@adobe/helix-md2jcr",
-  "version": "1.1.38",
+  "version": "1.2.1",
   "description": "Helix Service that converts markdown to JCR content structure",
   "main": "src/index.js",
   "type": "module",
+  "bin": {
+    "md2jcr": "./bin/md2jcr.js"
+  },
   "scripts": {
     "test": "c8 mocha 'test/*.tests.js'",
     "lint": "eslint .",

package/src/cli/convert2jcr.js

@@ -1,135 +0,0 @@
-/*
- * Copyright 2021 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.
- */
-
-/* eslint-disable no-await-in-loop,no-console */
-import {
-  readdir, readFile, stat, writeFile,
-} from 'fs/promises';
-import path from 'path';
-import { decode } from 'entities';
-import { md2jcr } from '../index.js';
-
-/**
- * Read a JSON file. If the file does not exist, return an empty object.
- * @param {string} filePath The path to the JSON file.
- * @returns {Promise<{}|any>} A promise that resolves to the JSON object in the file,
- */
-async function readJsonFile(filePath) {
-  try {
-    if ((await stat(filePath)).isFile()) {
-      const models = await readFile(filePath, 'utf-8');
-      return JSON.parse(models);
-    }
-  } catch (error) {
-    // ignore the fact that the file doesn't exist
-    // console.error(`Error due to: ${error} for file ${filePath}`);
-  }
-  return {};
-}
-
-/**
- * Convert a markdown file to JCR XML.
- * @param mdFile {string} The path to the markdown file.
- * @param verbose - if true the XML will be printed to the console.
- * @param decodeXML - if true a file with the decoded XML will be created.
- * @returns {Promise<void>} A promise that resolves when the conversion is
- * complete, or rejects if the file is not a markdown file.
- */
-async function convert(mdFile, verbose = false, decodeXML = false) {
-  if (!mdFile.endsWith('.md')) {
-    return Promise.reject(new Error('File must be a markdown file'));
-  }
-
-  const dir = path.dirname(mdFile);
-  const base = path.basename(mdFile, '.md');
-  const fileJcrXML = path.resolve(dir, `${base}.xml`);
-
-  let modelJson;
-  let definitionJson;
-  let filtersJson;
-
-  const blockDefinitionsPath = path.resolve(dir, `_${base}.json`);
-
-  // check to see if the blockFiles exists
-  try {
-    await stat(blockDefinitionsPath);
-    const blockDefinitionFile = await readJsonFile(path.resolve(dir, `_${base}.json`));
-    modelJson = blockDefinitionFile.models;
-    definitionJson = {
-      groups: [
-        {
-          title: 'Blocks',
-          id: 'blocks',
-          components: [
-            ...blockDefinitionFile.definitions,
-          ],
-        },
-      ],
-    };
-    filtersJson = blockDefinitionFile.filters;
-  } catch (err) {
-    const modelFile = path.resolve(dir, `${base}-models.json`);
-    const definitionFile = path.resolve(dir, `${base}-definitions.json`);
-    const filtersFile = path.resolve(dir, `${base}-filters.json`);
-    modelJson = await readJsonFile(modelFile);
-    definitionJson = await readJsonFile(definitionFile);
-    filtersJson = await readJsonFile(filtersFile);
-  }
-
-  const md = await readFile(mdFile, 'utf-8');
-
-  /** @type {Mdast2JCROptions} */
-  const opts = {
-    models: modelJson,
-    definition: definitionJson,
-    filters: filtersJson,
-  };
-
-  const xml = await md2jcr(md, opts);
-
-  if (verbose) {
-    if (!decodeXML) {
-      console.log(xml);
-    } else if (decodeXML) {
-      console.log(decode(xml));
-    }
-  }
-
-  return writeFile(fileJcrXML, xml);
-}
-
-/**
- * Entry point to convert a markdown file to JCR XML.
- * @param inPath {string} The path to the markdown file or directory containing
- * markdown files.
- * @returns {Promise<void>} A promise that resolves when the conversion is
- * complete.
- */
-async function run(inPath) {
-  const dirOrFilePath = path.resolve(process.cwd(), inPath);
-
-  const files = [];
-  if ((await stat(dirOrFilePath)).isDirectory()) {
-    const items = await readdir(dirOrFilePath);
-    items
-      .filter((item) => item.endsWith('.md'))
-      .forEach((item) => files.push(path.resolve(dirOrFilePath, item)));
-  } else {
-    files.push(dirOrFilePath);
-  }
-
-  for (const file of files) {
-    await convert(file, process.argv.includes('-v'), process.argv.includes('-d'));
-  }
-}
-
-run(process.argv[2] || process.cwd()).catch(console.error);