Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/liamfiddler/eleventy-plugin-transformdom
A plugin to process & change the generated HTML output of your Eleventy site.
https://github.com/liamfiddler/eleventy-plugin-transformdom
11ty dom eleventy html plugin transform
Last synced: 3 days ago
JSON representation
A plugin to process & change the generated HTML output of your Eleventy site.
- Host: GitHub
- URL: https://github.com/liamfiddler/eleventy-plugin-transformdom
- Owner: liamfiddler
- License: mit
- Created: 2020-10-08T22:49:25.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2023-11-30T12:29:00.000Z (10 months ago)
- Last Synced: 2024-09-21T13:04:20.097Z (6 days ago)
- Topics: 11ty, dom, eleventy, html, plugin, transform
- Language: JavaScript
- Homepage:
- Size: 40 KB
- Stars: 9
- Watchers: 1
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# DOM Transforming plugin
Process & change the generated HTML output of your [Eleventy](https://www.11ty.io/) 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](./examples/replace-text)
- 📝 [Set the page `title` tag to match the first heading on the page](./examples/page-title)
- 🌄 [Add `loading="lazy"` attributes to images](./examples/loading-lazy)
- 🌟 [Insert async content from an API](./examples/async-transform)
- 📃 [Append a script to the page (e.g. Google Analytics)](./examples/google-analytics)
- 🧩 [Import web components, but only on pages they're used](./examples/web-components)
- 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](https://paypal.me/liamfiddler) or [ko-fi](https://ko-fi.com/liamfiddler)**
---
## Getting started
### Install the plugin
In your project directory run:
```console
# 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:
```javascript
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](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) (`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[]`](https://github.com/jsdom/jsdom) | An array of elements in the DOM matching the provided `selector` |
| window | [`DOMWindow`](https://github.com/jsdom/jsdom) | The `window` of the generated HTML |
| document | [`Document`](https://github.com/jsdom/jsdom) | 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](https://www.11ty.dev/docs/config/#input-directory)) |
| outputDir | `string` | The directory inside which the finished templates will be written to by Eleventy ([see the Eleventy docs](https://www.11ty.dev/docs/config/#output-directory)) |
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](https://github.com/liamfiddler)
See also the list of
[contributors](https://github.com/liamfiddler/eleventy-plugin-transformdom/contributors)
who participated in this project.
## License
This project is licensed under the MIT License -
see the [LICENSE](LICENSE) file for details
## Acknowledgments
- The wonderfully supportive team at
[Future Friendly](https://futurefriendly.team)
- Everyone who has contributed to the
[11ty](https://www.11ty.io/) and [JSDOM](https://github.com/jsdom/jsdom) projects, without whom
this plugin wouldn't run
---
**Like this project? Buy me a coffee via [PayPal](https://paypal.me/liamfiddler) or [ko-fi](https://ko-fi.com/liamfiddler)**
---