metalsmith-markdown-partials 2.5.0 → 2.5.1

package/README.md

@@ -7,9 +7,15 @@ A Metalsmith plugin that enables the use of Markdown partials.
 [![license: MIT][license-badge]][license-url]
 [![coverage][coverage-badge]][coverage-url]
 [![ESM/CommonJS][modules-badge]][npm-url]
+[![Known Vulnerabilities](https://snyk.io/test/npm/metalsmith-markdown-partials/badge.svg)](https://snyk.io/test/npm/metalsmith-markdown-partials)
 
 Markdown fragments are inserted into the contents of a page markdown file by replacing an include marker with markdown partials. This allows for modular markdown and promotes reuse of content.
 
+## Features
+- This plugin supports both ESM and CommonJS environments with no configuration needed:
+  - ESM: `import mdPartials from 'metalsmith-markdown-partials'`
+  - CommonJS: `const mdPartials = require('metalsmith-markdown-partials')`
+
 ## Installation
 
 ```js
@@ -19,9 +25,6 @@ $ npm install --save metalsmith-markdown-partials
 ## Usage
 
 ```js
-var mdPartials = require('metalsmith-markdown-partials');
-
-...
 .use(mdPartials({
     libraryPath: './markdown-partials/',
     fileSuffix: '.md.njk',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metalsmith-markdown-partials",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "A Metalsmith plugin that allows the use of partial markdown files",
   "keywords": [
     "metalsmith-plugin",
@@ -22,8 +22,9 @@
     "url": "git+https://github.com/wernerglinka/metalsmith-markdown-partials.git"
   },
   "files": [
+    "src",
     "lib",
-    "LICENSE.md",
+    "LICENSE",
     "README.md"
   ],
   "author": {
@@ -38,16 +39,16 @@
   "scripts": {
     "build": "microbundle --entry src/index.js --output lib/index.js --target node -f esm,cjs --strict --generateTypes=false",
     "changelog": "auto-changelog -u --commit-limit false --ignore-commit-pattern '^((dev|chore|ci):|Release)'",
-    "coverage": "npm test && c8 report --reporter=text-lcov > ./coverage.info",
+    "coverage": "c8 --include=src/**/*.js --reporter=lcov --reporter=text-summary mocha 'test/index.js' 'test/cjs.test.cjs' -t 15000",
     "format": "prettier --write \"**/*.{yml,md,js,json}\"",
     "format:check": "prettier --list-different \"**/*.{yml,md,js,json}\"",
     "lint": "eslint --fix .",
     "lint:check": "eslint --fix-dry-run .",
     "prepublishOnly": "npm run build",
-    "update-coverage": "node scripts/update-coverage-badge.js",
-    "prerelease": "npm run update-coverage && git add README.md && git commit -m \"Update coverage badge in README\" || true",
-    "release": "npm run build && GITHUB_TOKEN=$(grep GITHUB_TOKEN .env | cut -d '=' -f2) ./node_modules/.bin/release-it . ",
-    "release:check": "npm run lint:check && npm run build && GITHUB_TOKEN=$(grep GITHUB_TOKEN .env | cut -d '=' -f2) ./node_modules/.bin/release-it . --dry-run",
+    "release:patch": "release-it patch",
+    "release:minor": "release-it minor",
+    "release:major": "release-it major",
+    "release:check": "npm run lint:check && npm run build && release-it --dry-run",
     "test": "c8 --include=src/**/*.js mocha 'test/index.js' 'test/cjs.test.cjs' -t 15000",
     "test:esm": "c8 --include=src/**/*.js mocha test/index.js -t 15000",
     "test:cjs": "c8 --include=src/**/*.js mocha test/cjs.test.cjs -t 15000",
@@ -57,13 +58,13 @@
   "devDependencies": {
     "auto-changelog": "^2.5.0",
     "c8": "^10.1.3",
-    "eslint": "^9.26.0",
-    "eslint-config-prettier": "^10.1.5",
+    "eslint": "^9.32.0",
+    "eslint-config-prettier": "^10.1.8",
     "metalsmith": "^2.6.3",
     "microbundle": "^0.15.1",
-    "mocha": "^11.2.2",
-    "prettier": "^3.5.3",
-    "release-it": "19.0.2"
+    "mocha": "^11.7.1",
+    "prettier": "^3.6.2",
+    "release-it": "19.0.4"
   },
   "peerDependencies": {
     "metalsmith": "^2.5.1"

package/src/index.js

@@ -0,0 +1,187 @@
+/**
+ * A Metalsmith plugin to merge markdown partials into main markdown files.
+ *
+ * @module metalsmith-markdown-partials
+ */
+
+/**
+ * @typedef {Object} Options
+ * @property {String} libraryPath - Path to the markdown partials library (defaults to './src/content/md-library/')
+ * @property {String} fileSuffix - File suffix for markdown files (defaults to '.md')
+ */
+
+// Define debug namespace at the top of the file
+const debugNs = 'metalsmith-markdown-partials';
+
+/** @type {Options} */
+const defaults = {
+  libraryPath: './src/content/md-library/',
+  fileSuffix: '.md'
+};
+
+/**
+ * Normalize plugin options by merging with defaults
+ * @param {Options} [options] - User provided options
+ * @returns {Options} Normalized options
+ */
+function normalizeOptions(options) {
+  return Object.assign({}, defaults, options || {});
+}
+
+/**
+ * Extract markdown partials from files and prepare them for insertion
+ *
+ * @param {Object} files - The metalsmith file object
+ * @param {Options} options - Plugin options
+ * @param {Function} debug - Debug function
+ * @returns {Array} Array with all markdown include objects
+ */
+function getMarkdownIncludes(files, options, debug) {
+  const markdownIncludes = [];
+
+  // Extract the library name from the path
+  const libraryPath = options.libraryPath.slice(0, -1).split('/');
+  const libraryName = libraryPath[libraryPath.length - 1];
+
+  debug('Processing markdown files with libraryName: %s', libraryName);
+
+  // Regex for matching include markers
+  const markerRegex = /\{#md\s*".+?"\s*#\}/g;
+  const markerStart = '{#md';
+  const markerEnd = '#}';
+
+  // Set to track already processed partials to prevent duplicates
+  const processedPartials = new Set();
+
+  Object.keys(files).forEach((file) => {
+    /*
+     * checks if string 'file' ends with options.fileSuffix
+     * when metalsmith-in-place or metalsmith-layouts are used
+     * the suffix depends on what templating language is used
+     * for example with Nunjucks it would be .md.njk
+     *
+     * Also check that file does NOT start with libraryName as
+     * the markdown partials library is also located in the content folder
+     */
+    if (file.endsWith(options.fileSuffix) && !file.startsWith(libraryName)) {
+      const str = files[file].contents.toString();
+
+      // Check if markers are present
+      const matches = str.match(markerRegex);
+      if (!matches) {return;}
+
+      debug('Found %d markdown partials in %s', matches.length, file);
+
+      // Process each marker in the file
+      matches.forEach((marker) => {
+        // Extract the filename from the marker
+        const markerFileName = marker.replaceAll(' ', '').replace(`${markerStart}"`, '').replace(`"${markerEnd}`, '');
+        const partialKey = `${libraryName}/${markerFileName}`;
+
+        // Check if partial file exists
+        if (!files[partialKey]) {
+          debug('Warning: Partial file not found: %s', partialKey);
+          return;
+        }
+
+        // Skip if we've already processed this exact marker+file combination
+        const combinedKey = `${file}:${marker}`;
+        if (processedPartials.has(combinedKey)) {return;}
+
+        processedPartials.add(combinedKey);
+
+        // Get the replacement content
+        const replacementString = files[partialKey].contents.toString();
+
+        markdownIncludes.push({
+          marker,
+          markerReplacement: replacementString,
+          file
+        });
+      });
+    }
+  });
+
+  // Remove markdown-partials from metalsmith build process
+  Object.keys(files).forEach((file) => {
+    if (file.startsWith(libraryName)) {
+      delete files[file];
+    }
+  });
+
+  debug('Processed %d markdown includes', markdownIncludes.length);
+  return markdownIncludes;
+}
+
+/**
+ * Replace markers with their markdown replacement strings
+ *
+ * @param {Object} files - The metalsmith file object
+ * @param {Array} markdownIncludes - Array with all markdown include objects
+ * @param {Function} debug - Debug function
+ * @return {void}
+ */
+function resolveMarkdownIncludes(files, markdownIncludes, debug) {
+  // replace all markers with their markdown replacements
+  markdownIncludes.forEach((markdownInclude) => {
+    const fileData = files[markdownInclude.file];
+
+    // replace the include marker with the actual include file content
+    try {
+      const contents = fileData.contents.toString();
+      fileData.contents = Buffer.from(contents.replace(markdownInclude.marker, markdownInclude.markerReplacement));
+      debug('Replaced marker in %s', markdownInclude.file);
+    } catch (e) {
+      debug('Error replacing marker in %s: %s', markdownInclude.file, e.message);
+      console.error(`Error replacing marker in ${markdownInclude.file}:`, e);
+    }
+  });
+}
+
+/**
+ * A Metalsmith plugin to merge markdown partials into main markdown file
+ *
+ * A marker of the form {#md "<file name>.md" #} indicates where the partial
+ * must be inserted and also provides the file name of the replacement markdown.
+ *
+ * @param {Options} [options] - Plugin options
+ * @returns {import('metalsmith').Plugin} Metalsmith plugin function
+ * @example
+ * // In your metalsmith build:
+ * .use(markdownPartials({
+ *   libraryPath: './src/content/md-partials/',
+ *   fileSuffix: '.md.njk'
+ * }))
+ */
+function initMarkdownPartials(options) {
+  options = normalizeOptions(options);
+
+  return function markdownPartials(files, metalsmith, done) {
+    // Use metalsmith's debug method if available
+    const debug = metalsmith.debug ? metalsmith.debug(debugNs) : () => {};
+    debug('Running with options: %o', options);
+
+    try {
+      // Get all markdown includes
+      const markdownIncludes = getMarkdownIncludes(files, options, debug);
+
+      // Replace include markers with their respective replacement
+      if (markdownIncludes.length) {
+        resolveMarkdownIncludes(files, markdownIncludes, debug);
+      }
+
+      setImmediate(done);
+    } catch (err) {
+      debug('Error processing markdown partials: %s', err.message);
+      setImmediate(() => done(err));
+    }
+  };
+}
+
+// ESM export
+export default initMarkdownPartials;
+
+// CommonJS export compatibility
+if (typeof module !== 'undefined') {
+  module.exports = initMarkdownPartials;
+}