@bryanfriedman/eleventy-html-relative-datacascade

Eleventy’s mode: "html-relative" passthrough copy works great for assets referenced directly from templates, but it doesn’t (yet) provide a built-in way to declare extra files to copy via the Data Cascade. This plugin bridges that gap: it reads an eleventyCopy property from page data and directory data files and mirrors matching assets from your input directories into the correct output folders, relative to each rendered HTML page.

Installation

npm install @bryanfriedman/eleventy-html-relative-datacascade

Usage

// eleventy.config.js (ESM)
import eleventyHtmlRelativeDataCascadePlugin from "@bryanfriedman/eleventy-html-relative-datacascade";

export default function (eleventyConfig) {
  eleventyConfig.addPassthroughCopy("**/*.{png,jpg}", {
    mode: "html-relative",
  });

  eleventyConfig.addPlugin(eleventyHtmlRelativeDataCascadePlugin, {
    extensions: [".html"], // output extensions to run on
    dot: false,            // include dotfiles in globs?
    failOnError: false     // throw or swallow copy/glob/JSON errors
  });

  return {};
}

Data Cascade sources

The plugin looks for eleventyCopy in:

• this.eleventyCopy
• this.page.eleventyCopy
• this.eleventy.data.eleventyCopy
• this.page.data.eleventyCopy
• Directory data files:
  • <dir>/<basename(dir)>.json
  • <dir>/<basename(dir)>.11tydata.json

Example

blog/blog.json:

{
  "eleventyCopy": [
    "*.png",
    "images/**/*.jpg"
  ]
}

For any page rendered from blog/, the plugin searches those patterns in the input blog/ directory and copies matches to the output blog/ directory (e.g., _site/blog/...), preserving relative paths.

Options

• extensions (string[], default: [".html"]): Output extensions to run on.
• dot (boolean, default: false): Whether to match dotfiles in globs.
• failOnError (boolean, default: false): Throw on glob / copy / JSON errors instead of swallowing them.

Upstream status

This package is a standalone implementation of an upstream Eleventy proposal to support Data Cascade–driven html-relative copying (e.g. eleventyCopy coming from directory data and page data).

Upstream references:

PR: https://github.com/11ty/eleventy/pull/3951
Issue: https://github.com/11ty/eleventy/issues/3881

If/when Eleventy merges and releases equivalent functionality in core, the core implementation should be preferred. In that event, this plugin will likely shift into one of these roles:

• Compatibility layer for older Eleventy versions, or
• Deprecated in favor of the core behavior (with guidance in this README).

Releasing

This repo uses tag-based automation:

• Pushing a tag like v0.1.0 will:
  • run CI tests
  • publish to npm
  • create a GitHub Release with autogenerated notes

Publish a new version

npm version patch   # or minor / major
git push --follow-tags