DOM Transforming plugin

Process & change the generated HTML output of your Eleventy site.

Configure the plugin with your CSS selectors and transform functions, then the plugin will run them on each HTML file generated by Eleventy.

Some of the things you could use it to do include:

• 🔠 Replace any text on the page
• 📝 Set the page title tag to match the first heading on the page
• 🌄 Add loading="lazy" attributes to images
• 🌟 Insert async content from an API
• 📃 Append a script to the page (e.g. Google Analytics)
• 🧩 Import web components, but only on pages they're used
• And more (we'd love to hear how you're using it, please get in touch!)

Like this project? Buy me a coffee via PayPal or ko-fi

Getting started

Install the plugin

In your project directory run:

# Using npm
npm install eleventy-plugin-transformdom --save-dev

# Or using yarn
yarn add eleventy-plugin-transformdom --dev

Then update your project's .eleventy.js to use the plugin:

const transformDomPlugin = require('eleventy-plugin-transformdom');

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(transformDomPlugin, [
    {
      selector: 'img',
      transform: ({ elements }) => {
        elements.forEach((img) => {
          img.setAttribute('loading', 'lazy');
        });
      },
    },
  ]);
};

☝️ The example above shows a Transform Item that finds all the images in your HTML and adds loading="lazy" to the markup. Read on to learn how to customise your own transforms.

Write your Transform Items

The plugin takes a Transform Item array as configuration.

A Transform Item is an Object that contains two keys; selector & transform

Each Transform Item will be run in order. This means you can write a Transform Item that modifies the DOM, then the next Transform Item can further modify the resulting DOM, and so on.

selector

The "selector" is a CSS selector (string).

Multiple selectors may be separated with commas.

transform

The "transform" is a function ((args) => void) that will be run on the generated HTML.

The function will be passed an Object as argument. The args Object has the following entries:

| Key | Type | Description | |---|---|---| | elements | Element[] | An array of elements in the DOM matching the provided selector | | window | DOMWindow | The window of the generated HTML | | document | Document | The window.document of the generated HTML | | inputPath | string | The source file path from which Eleventy is generating the HTML | | outputPath | string | The output path/filename of the HTML file being generated | | inputDir | string | The source directory from which Eleventy is building the site (see the Eleventy docs) | | outputDir | string | The directory inside which the finished templates will be written to by Eleventy (see the Eleventy docs) |

Note: async transform functions are supported, however they will be run in sequence to prevent race conditions.

Contributing

This project welcomes suggestions and Pull Requests!

Authors

• Liam Fiddler - Initial work / maintainer - @liamfiddler

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE file for details

Acknowledgments

• The wonderfully supportive team at Future Friendly
• Everyone who has contributed to the 11ty and JSDOM projects, without whom this plugin wouldn't run

Like this project? Buy me a coffee via PayPal or ko-fi