metalsmith-markdown-partials 2.3.1 → 2.4.0

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;
+}

package/test/cjs.test.cjs

@@ -0,0 +1,55 @@
+// Minimal CommonJS test file - just verifies the CJS module works
+const assert = require('node:assert').strict;
+const path = require('node:path');
+const fs = require('node:fs');
+const metalsmith = require('metalsmith');
+
+// Import the plugin using the CommonJS format
+const plugin = require('../lib/index.cjs');
+
+describe('metalsmith-markdown-partials (CommonJS)', () => {
+  // Verify the module loads correctly and exports a function
+  it('should be properly importable as a CommonJS module', () => {
+    assert.strictEqual(typeof plugin, 'function', 'Plugin should be a function when required with CommonJS');
+    assert.strictEqual(typeof plugin(), 'function', 'Plugin should return a function when called');
+  });
+  
+  // Add a basic functionality test to verify the plugin works
+  it('should process markdown partials correctly', (done) => {
+    const fixturesDir = path.join(__dirname, 'fixtures');
+    
+    const instance = plugin({
+      libraryPath: path.join(fixturesDir, '/src/md-partials/'),
+      fileSuffix: '.md',
+    });
+
+    // Create a fake metalsmith instance
+    const metalsmithInstance = metalsmith(fixturesDir);
+    
+    // Load a test file
+    const markdownContent = fs.readFileSync(path.join(fixturesDir, 'src/markdown.md'), 'utf8');
+    const partialContent = fs.readFileSync(path.join(fixturesDir, 'src/md-partials/test-partial.md'), 'utf8');
+    const expectedContent = fs.readFileSync(path.join(fixturesDir, 'expected/final-markdown.md'), 'utf8');
+    
+    // Setup files object
+    const files = {
+      'markdown.md': {
+        contents: Buffer.from(markdownContent)
+      },
+      'md-partials/test-partial.md': {
+        contents: Buffer.from(partialContent)
+      }
+    };
+    
+    // Run the plugin
+    instance(files, metalsmithInstance, (err) => {
+      assert.strictEqual(err, undefined, 'No error should occur');
+      assert.strictEqual(
+        files['markdown.md'].contents.toString().trim(),
+        expectedContent.trim(),
+        'Content should be properly processed'
+      );
+      done();
+    });
+  });
+});

package/test/index.js

@@ -0,0 +1,139 @@
+// ESM test file for Metalsmith plugins
+import { strict as assert } from 'node:assert';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve, join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import metalsmith from 'metalsmith';
+
+// Import the plugin directly from src for accurate coverage
+import plugin from '../src/index.js';
+
+// Get current directory and setup path utilities
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = resolve.bind(resolve, __dirname, 'fixtures');
+
+function file(_path) {
+  return readFileSync(fixture(_path), 'utf8');
+}
+
+describe('metalsmith-markdown-partials (ESM)', () => {
+  // Verify ESM module loading
+  it('should be importable as an ES module', () => {
+    assert.strictEqual(typeof plugin, 'function', 'Plugin should be a function when imported with ESM');
+    assert.strictEqual(typeof plugin(), 'function', 'Plugin should return a function when called');
+  });
+
+  it('should replace marker with markdown partial', (done) => {
+    metalsmith(fixture())
+      .use(
+        plugin({
+          libraryPath: join(fixture(), `/src/md-partials/`),
+          fileSuffix: '.md'
+        })
+      )
+      .build((err) => {
+        if (err) {
+          return done(err);
+        }
+        assert.strictEqual(
+          file('build/markdown.md').trim(),
+          file('expected/final-markdown.md').trim(),
+          'Content should match expected output'
+        );
+        done();
+      });
+  });
+
+  it('should use metalsmith debug when available', (done) => {
+    // Create a mock debug function that records calls
+    const debugCalls = [];
+    const mockMetalsmith = {
+      debug:
+        () =>
+        (...args) => {
+          debugCalls.push(args);
+          return true;
+        }
+    };
+
+    // Create test files
+    const files = {
+      'test.md': {
+        contents: Buffer.from('Test content {#md "partial.md" #} more content')
+      },
+      'md-partials/partial.md': {
+        contents: Buffer.from('Partial content')
+      }
+    };
+
+    // Create and call the plugin
+    const pluginInstance = plugin({
+      libraryPath: './md-partials/',
+      fileSuffix: '.md'
+    });
+
+    pluginInstance(files, mockMetalsmith, () => {
+      assert(debugCalls.length > 0, 'Debug function should have been called');
+      assert(debugCalls[0][0].includes('options'), 'Should include options message');
+      done();
+    });
+  });
+
+  it('should handle missing debug method gracefully', (done) => {
+    // Create a metalsmith mock without debug method
+    const mockMetalsmith = {};
+
+    // Create test files
+    const files = {
+      'test.md': {
+        contents: Buffer.from('Test content {#md "partial.md" #} more content')
+      },
+      'md-partials/partial.md': {
+        contents: Buffer.from('Partial content')
+      }
+    };
+
+    // Should not throw error when debug is missing
+    const pluginInstance = plugin({
+      libraryPath: './md-partials/',
+      fileSuffix: '.md'
+    });
+
+    pluginInstance(files, mockMetalsmith, (err) => {
+      assert.strictEqual(err, undefined, 'No error should occur when debug is missing');
+      done();
+    });
+  });
+
+  it('should handle files without markers correctly', (done) => {
+    // Create a metalsmith mock
+    const mockMetalsmith = {};
+
+    // Create test files
+    const files = {
+      'test.md': {
+        contents: Buffer.from('Test content without any markers')
+      },
+      'md-partials/partial.md': {
+        contents: Buffer.from('Partial content')
+      }
+    };
+
+    // Should not throw error when no markers are found
+    const pluginInstance = plugin({
+      libraryPath: './md-partials/',
+      fileSuffix: '.md'
+    });
+
+    pluginInstance(files, mockMetalsmith, (err) => {
+      assert.strictEqual(err, undefined, 'No error should occur when no markers are present');
+      // Content should remain unchanged
+      assert.strictEqual(
+        files['test.md'].contents.toString(),
+        'Test content without any markers',
+        'Content should remain unchanged'
+      );
+      done();
+    });
+  });
+});

package/.eslintcache

@@ -1 +0,0 @@
-[{"/Users/wernerglinka/Documents/Projects/1-SANDBOXES/metalsmith-sandbox/>>>plugins/ms-markdown-partials/lib/index.js":"1","/Users/wernerglinka/Documents/Projects/1-SANDBOXES/metalsmith-sandbox/>>>plugins/ms-markdown-partials/tests/index.js":"2"},{"size":4171,"mtime":1644358226139,"results":"3","hashOfConfig":"4"},{"size":862,"mtime":1643928622922,"results":"5","hashOfConfig":"4"},{"filePath":"6","messages":"7","suppressedMessages":"8","errorCount":0,"fatalErrorCount":0,"warningCount":0,"fixableErrorCount":0,"fixableWarningCount":0},"uajcbk",{"filePath":"9","messages":"10","suppressedMessages":"11","errorCount":0,"fatalErrorCount":0,"warningCount":0,"fixableErrorCount":0,"fixableWarningCount":0},"/Users/wernerglinka/Documents/Projects/1-SANDBOXES/metalsmith-sandbox/>>>plugins/ms-markdown-partials/lib/index.js",[],[],"/Users/wernerglinka/Documents/Projects/1-SANDBOXES/metalsmith-sandbox/>>>plugins/ms-markdown-partials/tests/index.js",[],[]]

package/.nyc_output/181518ec-15ce-4116-8650-58fc4a5be71d.json

@@ -1 +0,0 @@
-{}

package/.nyc_output/processinfo/181518ec-15ce-4116-8650-58fc4a5be71d.json

@@ -1 +0,0 @@
-{"parent":null,"pid":96565,"argv":["/Users/wernerglinka/.nvm/versions/node/v18.16.0/bin/node","/Users/wernerglinka/Documents/Projects/Metalsmith/>>>plugins/ms-markdown-partials/node_modules/.bin/mocha","./tests/index.js"],"execArgv":[],"cwd":"/Users/wernerglinka/Documents/Projects/Metalsmith/>>>plugins/ms-markdown-partials","time":1731375730889,"ppid":96562,"coverageFilename":"/Users/wernerglinka/Documents/Projects/Metalsmith/>>>plugins/ms-markdown-partials/.nyc_output/181518ec-15ce-4116-8650-58fc4a5be71d.json","externalId":"","uuid":"181518ec-15ce-4116-8650-58fc4a5be71d","files":[]}

package/.nyc_output/processinfo/index.json

@@ -1 +0,0 @@
-{"processes":{"181518ec-15ce-4116-8650-58fc4a5be71d":{"parent":null,"children":[]}},"files":{},"externalIds":{}}

package/.prettierrc.yml

@@ -1,7 +0,0 @@
-trailingComma: none
-tabWidth: 2
-semi: true
-singleQuote: true
-bracketSpacing: true
-arrowParens: always
-printWidth: 120

package/tests/index.js

@@ -1,42 +0,0 @@
-/* global describe, it */
-
-'use strict';
-
-import * as chai from 'chai';
-import metalsmith from 'metalsmith';
-import mdPartials from '../lib/index.js';
-import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
-
-/* eslint-disable no-underscore-dangle */
-const __dirname = dirname( fileURLToPath( import.meta.url ) );
-
-const { expect } = chai;
-
-const fixture = path.resolve.bind( path, __dirname, 'fixtures' );
-
-function file( _path ) {
-  return fs.readFileSync( fixture( _path ), 'utf8' );
-}
-
-describe( 'metalsmith-markdown-partials', () => {
-
-  it( 'should replace marker with markdown partial', done => {
-
-    metalsmith( fixture() )
-      .use( mdPartials( {
-        libraryPath: path.join( fixture(), `/src/md-partials/` ),
-        fileSuffix: '.md',
-      } ) )
-      .build( err => {
-        if ( err ) {
-          return done( err );
-        }
-        expect( file( 'build/markdown.md' ) ).to.be.eql( file( 'expected/final-markdown.md' ) );
-
-        done();
-      } );
-  } );
-} );