feat: handle markdown-it plugins with options (#207)

README.md

@@ -37,6 +37,26 @@ module.exports = function (config) {
 
 ## Usage
 
+For any options passed to `eleventy-plugin-fluid` in the configurations described below, you can override the default
+rather than merging with it by passing the option with `override:` as a prefix to the key. For example, to override the
+default options for the `css` configuration block, you could do the following:
+
+```diff
+const fluidPlugin = require("eleventy-plugin-fluid");
+
+module.exports = function (config) {
+-    config.addPlugin(fluidPlugin);
++    config.addPlugin(fluidPlugin, {
++        "override:css": {
++              // Your options here.
++        }
++    });
+};
+```
+
+Note that if you don't override required defaults when using this method, your configuration will not be valid, so
+proceed with caution if you are using this technique.
+
 ### Asset Handling
 
 `eleventy-plugin-fluid` includes configuration for processing and bundling Sass and CSS files using [Sass](https://sass-lang.com)
@@ -413,14 +433,16 @@ registering `eleventy-plugin-fluid` as follows:
 
 ```diff
 const fluidPlugin = require("eleventy-plugin-fluid");
-+ const markdownItEmoji = require("markdown-it-emoji");
 
 module.exports = function (config) {
 -    config.addPlugin(fluidPlugin);
 +    config.addPlugin(fluidPlugin, {
 +        markdown: {
 +            plugins: [
-+                markdownItEmoji
++                // The npm package name of the plugin, which must be installed in your project.
++                "markdown-it-emoji",
++                // The npm package name of the plugin, which must be installed in your project, and an options object for the plugin.
++                ["markdown-it-anchor", {}]
 +            ]
 +        }
 +    });

eleventy.config.js

@@ -12,11 +12,17 @@ https://github.com/fluid-project/eleventy-plugin-fluid/raw/main/LICENSE.md.
 "use strict";
 
 const fluidPlugin = require("./index.js");
+const slugify = require("@sindresorhus/slugify");
 
 const inputPath = "fixtures";
 
 module.exports = function (eleventyConfig) {
     eleventyConfig.addPlugin(fluidPlugin, {
+        markdown: {
+            plugins: [
+                ["markdown-it-anchor", { slugify: s => slugify(s) }]
+            ]
+        },
         sass: {
             enabled: true
         },

index.js

@@ -30,12 +30,12 @@ const languages = require("./src/config/languages.json");
 const compileCss = require("./src/compilers/compile-css.js");
 const compileSass = require("./src/compilers/compile-sass.js");
 const compileJs = require("./src/compilers/compile-js.js");
-const deepMerge = require("./src/utils/deep-merge.js");
+const merge = require("@11ty/eleventy/src/Util/Merge.js");
 
 module.exports = {
     initArguments: {},
     configFunction: function (eleventyConfig, options = {}) {
-        options = deepMerge({
+        options = merge({
             uio: true,
             markdown: {
                 options: {
@@ -118,8 +118,11 @@ module.exports = {
 
             const md = new MarkdownIt(options.markdown.options);
             options.markdown.plugins.forEach(plugin => {
-                if (plugin) {
+                if (typeof plugin === "string") {
                     md.use(require(plugin));
+                } else {
+                    const [pluginPackage, options = {}] = plugin;
+                    md.use(require(pluginPackage), options);
                 }
             });
 
@@ -156,9 +159,12 @@ module.exports = {
         /** Template Formats */
         eleventyConfig.amendLibrary("md", md => {
             md.set(options.markdown.options);
-            Object.values(options.markdown.plugins).forEach(plugin => {
-                if (plugin) {
+            options.markdown.plugins.forEach(plugin => {
+                if (typeof plugin === "string") {
                     md.use(require(plugin));
+                } else {
+                    const [pluginPackage, options = {}] = plugin;
+                    md.use(require(pluginPackage), options);
                 }
             });
         });

package.json

@@ -37,6 +37,7 @@
     "fluid-lint-all": "1.2.9",
     "husky": "8.0.3",
     "infusion": "4.6.0",
+    "markdown-it-anchor": "8.6.7",
     "rimraf": "5.0.1"
   },
   "dependencies": {

test/build.test.js

@@ -41,7 +41,7 @@ test("Builds minified JavaScript", async function (t) {
 
 test("Renders Markdown via shortcode", async function (t) {
     let testHtml = fs.readFileSync("_site/test.html", "utf8");
-    t.true(testHtml.includes("<h1>eleventy-plugin-fluid</h1>"));
+    t.true(testHtml.includes("<h1 id=\"eleventy-plugin-fluid\" tabindex=\"-1\">eleventy-plugin-fluid</h1>"));
 });
 
 test("Doesn't render unsupported template language via shortcode", async function (t) {

test/merge.test.js

@@ -0,0 +1,39 @@
+/*
+Copyright the eleventy-plugin-fluid copyright holders.
+
+See the AUTHORS.md file at the top-level directory of this distribution and at
+https://github.com/fluid-project/eleventy-plugin-fluid/raw/main/AUTHORS.md.
+
+Licensed under the New BSD license. You may not use this file except in compliance with this License.
+
+You may obtain a copy of the New BSD License at
+https://github.com/fluid-project/eleventy-plugin-fluid/raw/main/LICENSE.md.
+*/
+"use strict";
+
+const test = require("ava");
+const merge = require("@11ty/eleventy/src/Util/Merge.js");
+
+test("Passing false replaces an original value", function (t) {
+    t.deepEqual(merge({browserslist: "> 2%"}, {browserslist: false}), {browserslist: false});
+});
+
+test("Passing key with override prefix overrides an original value", function (t) {
+    t.deepEqual(merge({browserslist: "> 2%"}, {"override:browserslist": "> 1%"}), {browserslist: "> 1%"});
+});
+
+test("Nested objects can be merged", function (t) {
+    t.deepEqual(merge({drafts: {nesting: true}}, {drafts: {customMedia: true}}), {drafts: {nesting: true, customMedia: true}});
+});
+
+test("Nested objects can be overriden", function (t) {
+    t.deepEqual(merge({drafts: {nesting: true}}, {"override:drafts": {customMedia: true}}), {drafts: {customMedia: true}});
+});
+
+test("Nested arrays can be merged", function (t) {
+    t.deepEqual(merge({browserslist: ["ie 8", "ie 9"]}, {browserslist: ["ie 7"]}), {browserslist: ["ie 8", "ie 9", "ie 7"]});
+});
+
+test("Nested arrays can be overridden", function (t) {
+    t.deepEqual(merge({browserslist: ["ie 8", "ie 9"]}, {"override:browserslist": ["ie 7"]}), {browserslist: ["ie 7"]});
+});