Add support for both CJS/ESM plugins

docs/_markbind/variables.md

@@ -11,7 +11,7 @@
 <variable name="icon_info">:fas-info-circle:</variable>
 <variable name="icon_ticked">:far-check-square:</variable>
 
-<variable name="node_version_number">22</variable>
+<variable name="node_version_number">22.12</variable>
 <variable name="node_dev_version_number">22.22.0</variable>
 <variable name="node_version"><tooltip content="MarkBind aims to support up to the last maintenance lts release as outlined [here](https://nodejs.org/en/about/releases/)">v{{ node_version_number }}</tooltip></variable>
 <variable name="node_dev_version"><tooltip content="MarkBind aims to support up to the last maintenance lts release as outlined [here](https://nodejs.org/en/about/releases/)">v{{ node_dev_version_number }}</tooltip></variable>

docs/devGuide/development/writingPlugins.md

@@ -51,25 +51,72 @@ That is, the DOM tree being processed during `processNode` and the content passe
 
 An example of a plugin is shown below. The plugin shows two ways of appending a paragraph of text to a specific `div` in the Markdown files:
 
-```js
-// myPlugin.js
+<tabs>
+  <tab header="CJS">
 
-const cheerio = module.parent.require('cheerio');
+  ```js
+  // myPlugin.js
 
-module.exports = {
-  processNode: (pluginContext, node) => {
-    if (node.attribs.id === 'my-div') {
-      cheerio(node).append(pluginContext.content);
-    }
-  },
-  postRender: (pluginContext, frontmatter, content) => {
-    const $ = cheerio.load(content, { xmlMode: false });
+  const cheerio = module.parent.require('cheerio');
+
+  module.exports = {
+    processNode: (pluginContext, node) => {
+      if (node.attribs.id === 'my-div') {
+        cheerio(node).append(pluginContext.content);
+      }
+    },
+    postRender: (pluginContext, frontmatter, content) => {
+      const $ = cheerio.load(content, { xmlMode: false });
+      // Modify the page...
+      $('#my-div').append(pluginContext.content);
+      return $.html();
+    },
+  };
+  ```
+  </tab>
+  <tab header="ESM">
+
+  ```js
+  // myESMPlugin.js
+
+  import { load } from 'cheerio';
+
+  function postRender(pluginContext, frontmatter, content) {
+    const $ = load(content);
     // Modify the page...
     $('#my-div').append(pluginContext.content);
     return $.html();
-  },
-};
-```
+  }
+
+  export { postRender };
+  ```
+  </tab>
+</tabs>
+
+<box type="info" header="ESM plugin compatibility">
+
+<panel header="Info" type="seamless" minimized>
+
+Both CJS and ESM plugins are supported. However, ESM plugins must meet the following requirements:
+
+1. The module is fully synchronous (contains no top-level await); and
+2. One of these conditions are met:
+   - The file has a **`.mjs` extension**, or
+   - The file has a **`.js` extension** and the closest `package.json` contains `"type": "module"`, or
+   - The file has a **`.js` extension** and the module source contains ES module syntax 
+
+Furthermore, **ESM plugins need to manage their own dependencies**, as `module.parent.require()` is not available in ESM. ESM Plugins should be bundled with their own dependencies (e.g. in a nearby `node_modules` folder.)
+
+</panel>
+</box>
+
+<box type="tip" header="Unsure if you're using CJS or ESM?">
+
+Generally, if your plugin has `require(...)` and `module.exports`, it is **CJS**.
+
+Alternatively, if your plugin has `import { ... }` and `export { ... }` it is **ESM**.
+</box>
+
 <box type="warning">
 
 Remember to update `dg-site.json`, `site.json`, and `ug-site.json` in the docs folder when updating the requirements for `site.json`.
@@ -197,4 +244,4 @@ To do this, you may implement the `beforeSiteGenerate` method.
   * No return value is required.
 
 {% from "njk/common.njk" import previous_next %}
-{{ previous_next('writingComponents', 'migratingToTypeScript') }}
+{{ previous_next('writingComponents', 'migratingToTypeScript') }}

packages/cli/test/functional/testSites.ts

@@ -8,6 +8,7 @@ const testSites = [
   'test_site_algolia_plugin',
   'test_site_special_tags',
   'test_site_table_plugin',
+  'test_site_custom_plugins',
 ];
 
 const testConvertSites = [

packages/cli/test/functional/test_site_custom_plugins/_markbind/layouts/default.md

@@ -0,0 +1,14 @@
+<header>
+
+</header>
+
+<div id="flex-body">
+  <div id="content-wrapper">
+    {{ content }}
+  </div>
+  <scroll-top-button></scroll-top-button>
+</div>
+
+<footer>
+
+</footer>

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/cjs_module_scope/cjs_plugin_with_cjs_ext.cjs

@@ -0,0 +1,12 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (pluginContext, frontmatter, content) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#cjs_module_scope_cjs_plugin_with_cjs_ext').append(
+      'Should work! (CJS module with .cjs extension in CJS module scope)',
+    );
+    return $.html();
+  },
+};

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/cjs_module_scope/cjs_plugin_without_cjs_ext.js

@@ -0,0 +1,12 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (pluginContext, frontmatter, content) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#cjs_module_scope_cjs_plugin_without_cjs_ext').append(
+      'Should work! (CJS module without .cjs extension in CJS module scope)',
+    );
+    return $.html();
+  },
+};

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/cjs_module_scope/esm_plugin_with_mjs_ext.mjs

@@ -0,0 +1,12 @@
+import cheerio from 'cheerio';
+
+function postRender(pluginContext, frontmatter, content) {
+  const $ = cheerio.load(content);
+  // Modify the page...
+  $('#cjs_module_scope_esm_plugin_with_mjs_ext').append(
+    'Should work! (ESM module with .mjs extension in CJS module scope)',
+  );
+  return $.html();
+}
+
+export { postRender };

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/cjs_module_scope/esm_plugin_without_mjs_ext.js

@@ -0,0 +1,12 @@
+import cheerio from 'cheerio';
+
+function postRender(pluginContext, frontmatter, content) {
+  const $ = cheerio.load(content);
+  // Modify the page...
+  $('#cjs_module_scope_esm_plugin_without_mjs_ext').append(
+    '**SHOULD SKIP** (ESM module without .mjs extension in CJS module scope)',
+  );
+  return $.html();
+}
+
+export { postRender };

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/cjs_module_scope/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/esm_module_scope/cjs_plugin_with_cjs_ext.cjs

@@ -0,0 +1,12 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (pluginContext, frontmatter, content) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#esm_module_scope_cjs_plugin_with_cjs_ext').append(
+      'Should work! (CJS module with .cjs extension in ESM module scope)',
+    );
+    return $.html();
+  },
+};

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/esm_module_scope/cjs_plugin_without_cjs_ext.js

@@ -0,0 +1,12 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (pluginContext, frontmatter, content) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#esm_module_scope_cjs_plugin_without_cjs_ext').append(
+      '**SHOULD SKIP** (CJS module without .cjs extension in ESM module scope)',
+    );
+    return $.html();
+  },
+};

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/esm_module_scope/esm_plugin_with_mjs_ext.mjs

@@ -0,0 +1,12 @@
+import cheerio from 'cheerio';
+
+function postRender(pluginContext, frontmatter, content) {
+  const $ = cheerio.load(content);
+  // Modify the page...
+  $('#esm_module_scope_esm_plugin_with_mjs_ext').append(
+    'Should work! (ESM module with .mjs extension in ESM module scope)',
+  );
+  return $.html();
+}
+
+export { postRender };

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/esm_module_scope/esm_plugin_without_mjs_ext.js

@@ -0,0 +1,12 @@
+import cheerio from 'cheerio';
+
+function postRender(pluginContext, frontmatter, content) {
+  const $ = cheerio.load(content);
+  // Modify the page...
+  $('#esm_module_scope_esm_plugin_without_mjs_ext').append(
+    'Should work! (ESM module without .mjs extension in ESM module scope)',
+  );
+  return $.html();
+}
+
+export { postRender };

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/esm_module_scope/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/no_module_scope/cjs_plugin_with_cjs_ext.cjs

@@ -0,0 +1,12 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (pluginContext, frontmatter, content) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#no_module_scope_cjs_plugin_with_cjs_ext').append(
+      'Should work! (CJS module with .cjs extension not in any module scope)',
+    );
+    return $.html();
+  },
+};

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/no_module_scope/cjs_plugin_without_cjs_ext.js

@@ -0,0 +1,12 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (pluginContext, frontmatter, content) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#no_module_scope_cjs_plugin_without_cjs_ext').append(
+      'Should work! (CJS module without .cjs extension not in any module scope)',
+    );
+    return $.html();
+  },
+};

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/no_module_scope/esm_plugin_with_mjs_ext.mjs

@@ -0,0 +1,12 @@
+import cheerio from 'cheerio';
+
+function postRender(pluginContext, frontmatter, content) {
+  const $ = cheerio.load(content);
+  // Modify the page...
+  $('#no_module_scope_esm_plugin_with_mjs_ext').append(
+    'Should work! (ESM module with .mjs extension not in any module scope)',
+  );
+  return $.html();
+}
+
+export { postRender };

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/no_module_scope/esm_plugin_without_mjs_ext.js

@@ -0,0 +1,12 @@
+import cheerio from 'cheerio';
+
+function postRender(pluginContext, frontmatter, content) {
+  const $ = cheerio.load(content);
+  // Modify the page...
+  $('#no_module_scope_esm_plugin_without_mjs_ext').append(
+    'Should work! (ESM module without .mjs extension not in any module scope)',
+  );
+  return $.html();
+}
+
+export { postRender };

packages/cli/test/functional/test_site_custom_plugins/_markbind/plugins/no_module_scope/package.json

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

packages/cli/test/functional/test_site_custom_plugins/expected/_markbind/plugins/cjs_module_scope/cjs_plugin_with_cjs_ext.cjs

@@ -0,0 +1,12 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (pluginContext, frontmatter, content) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#cjs_module_scope_cjs_plugin_with_cjs_ext').append(
+      'Should work! (CJS module with .cjs extension in CJS module scope)',
+    );
+    return $.html();
+  },
+};

packages/cli/test/functional/test_site_custom_plugins/expected/_markbind/plugins/cjs_module_scope/cjs_plugin_without_cjs_ext.js

@@ -0,0 +1,12 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (pluginContext, frontmatter, content) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#cjs_module_scope_cjs_plugin_without_cjs_ext').append(
+      'Should work! (CJS module without .cjs extension in CJS module scope)',
+    );
+    return $.html();
+  },
+};

packages/cli/test/functional/test_site_custom_plugins/expected/_markbind/plugins/cjs_module_scope/esm_plugin_with_mjs_ext.mjs

@@ -0,0 +1,12 @@
+import cheerio from 'cheerio';
+
+function postRender(pluginContext, frontmatter, content) {
+  const $ = cheerio.load(content);
+  // Modify the page...
+  $('#cjs_module_scope_esm_plugin_with_mjs_ext').append(
+    'Should work! (ESM module with .mjs extension in CJS module scope)',
+  );
+  return $.html();
+}
+
+export { postRender };

packages/cli/test/functional/test_site_custom_plugins/expected/_markbind/plugins/cjs_module_scope/esm_plugin_without_mjs_ext.js

@@ -0,0 +1,12 @@
+import cheerio from 'cheerio';
+
+function postRender(pluginContext, frontmatter, content) {
+  const $ = cheerio.load(content);
+  // Modify the page...
+  $('#cjs_module_scope_esm_plugin_without_mjs_ext').append(
+    '**SHOULD SKIP** (ESM module without .mjs extension in CJS module scope)',
+  );
+  return $.html();
+}
+
+export { postRender };

packages/cli/test/functional/test_site_custom_plugins/expected/_markbind/plugins/cjs_module_scope/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

packages/cli/test/functional/test_site_custom_plugins/expected/_markbind/plugins/esm_module_scope/cjs_plugin_with_cjs_ext.cjs

@@ -0,0 +1,12 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (pluginContext, frontmatter, content) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#esm_module_scope_cjs_plugin_with_cjs_ext').append(
+      'Should work! (CJS module with .cjs extension in ESM module scope)',
+    );
+    return $.html();
+  },
+};

packages/cli/test/functional/test_site_custom_plugins/expected/_markbind/plugins/esm_module_scope/cjs_plugin_without_cjs_ext.js

@@ -0,0 +1,12 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (pluginContext, frontmatter, content) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#esm_module_scope_cjs_plugin_without_cjs_ext').append(
+      '**SHOULD SKIP** (CJS module without .cjs extension in ESM module scope)',
+    );
+    return $.html();
+  },
+};

packages/cli/test/functional/test_site_custom_plugins/expected/_markbind/plugins/esm_module_scope/esm_plugin_with_mjs_ext.mjs

@@ -0,0 +1,12 @@
+import cheerio from 'cheerio';
+
+function postRender(pluginContext, frontmatter, content) {
+  const $ = cheerio.load(content);
+  // Modify the page...
+  $('#esm_module_scope_esm_plugin_with_mjs_ext').append(
+    'Should work! (ESM module with .mjs extension in ESM module scope)',
+  );
+  return $.html();
+}
+
+export { postRender };