Adds html-relative Passthrough Copy mode for relative asset references in HTML #3552

[zachleat]

export default async function(eleventyConfig) {
	// glob here is relative to project root
	eleventyConfig.addPassthroughCopy("content/**/*.mp4", {
		mode: "html-relative"
	});
}

Works great with emulated passthrough copy, too: https://www.11ty.dev/docs/copy/#emulate-passthrough-copy-during-serve

Why (and why not) use this?

Compared with using eleventyConfig.addPassthroughCopy('content/**/*.mp4'),

HtmlRelativeCopy is better because:

1. it handles relative URLs (and any customizations to permalink) seamlessly without requiring any changes to source content.
   • e.g. <video src="video.mp4"> on template.njk will copy to _site/template/video.mp4 alongside _site/template/index.html
   • e.g. <video src="assets/video.mp4"> on subdir/template.njk will copy to _site/subdir/template/assets/video.mp4 alongside _site/subdir/template/index.html
2. only copies files that are used by templates.

HtmlRelativeCopy may be worse when:

1. you aren’t using HTML if your template is not writing an HTML file in output
2. the reference in your HTML is not found by @11ty/posthtml-urls: https://github.com/11ty/eleventy-posthtml-urls/blob/d3097f44868737627555ebec622b029d7c0b1ab3/lib/defaultOptions.js#L10-L35
3. it has some build cost, this uses an opt-in posthtml transform (though you’re already feeling this cost if you use the InputPathToUrl, IdAttribute, or HTMLBase plugins)

Restrictions

Some other differences from the usual eleventyConfig.addPassthroughCopy:

• dot files are filtered from html-relative copy by default (via the dot: false recursive-copy option)
• source files must be in the current project directory.
• URLs and any absolute paths are ignored (we may add support for absolute paths later, if folks want it)

Full options list

export default async function(eleventyConfig) {
	// glob or Array of globs to match for copy
	eleventyConfig.addPassthroughCopy("**/*.png", {
		mode: "auto",
		paths: [], // additional fallback directories to look for source files
		failOnError: true, // throw an error when a path matches (via `match`) but not found on file system
		copyOptions: { dot: false }, // `recursive-copy` copy options
	});
}

• copyOptions matches the additional options passed to the recursive-copy package, see https://www.11ty.dev/docs/copy/#advanced-options
• Use copyOptions.overwrite: false to skip overwrite if a file already exists in the output directory.

[darthmall]

I have a few questions:

First, in your example with <video src=video.mp4> writing out both _site/template/video.mp4 and _site/template/index.html, where does video.mp4 live? Does it need to live in content/template/video.mp4?

Second, why make this a plugin? I understand wanting to maintain backwards compatibility for the existing passthrough copy function, but couldn't you achieve that by adding options to the passthrough copy function with default values that result in the existing behavior? I feel like having two different ways to copy static assets is going to be a little confusing, especially if the idea is that the built-in one is the one with which people struggle, and the one people probably want because it's more efficient and convenient is a plugin you have to import and add. Personally, I also just find the built-in plugins annoying because it means I have to have extra import statements at the top of my config file for something that is included when I npm install @11ty/eleventy.

Third, when you say "AutoCopy may be worse when you're not using HTML", does that mean when I'm using Markdown?

[Ryuno-Ki]

Third, when you say "AutoCopy may be worse when you're not using HTML", does that mean when I'm using Markdown?

You can write to JSON also.

[zachleat]

First, in your example with

Yep! Alternatively there is a paths feature to list directories that can be used as fallback search

Second, why make this a plugin?

Fair point! Let me think about it a bit—it might be more ergonomic to extend the eleventyConfig.addPassthroughCopy method instead!

Third, when you say "AutoCopy may be worse when you're not using HTML", does that mean when I'm using Markdown?

Anything that outputs to HTML is handled by this method (Markdown, Nunjucks, Liquid, 11ty.js, etc etc)! Updated the comment above: you aren’t using HTML your template output format is not .html

[zachleat]

Per @darthmall’s excellent feedback I’ve reworked the API to use eleventyConfig.addPassthroughCopy(glob, { mode: "auto" }) (open to better naming feedback on mode: "auto" not sure if I’m super happy with that). Code samples above have been updated too.

I love this change, thanks for the idea Evan!

(Still open to feedback here!)

A few other naming ideas:

• mode: "output-relative"
• mode: "relative"
• mode: "template-relative"

[wavebeem]

Per @darthmall’s excellent feedback I’ve reworked the API to use eleventyConfig.addPassthroughCopy(glob, { mode: "auto" }) (open to better naming feedback on mode: "auto" not sure if I’m super happy with that). Code samples above have been updated too.

I love this change, thanks for the idea Evan!

(Still open to feedback here!)

A few other naming ideas:

* `mode: "output-relative"`

* `mode: "relative"`

* `mode: "template-relative"`

I finally got around to testing this and had been banging my head on it for like 30 minutes before I thought to check back on this thread and see you're going in a different direction 😅

Couldn't figure out why AutoCopyPlugin was undefined.

"auto" isn't especially specific, and boxes in the API if you want to make a new style in the future (hopefully not, but you never know). The way I'm seeing this mode is... files are statically analyzed from HTML only, right? It feels like a name that reflects the static analysis of HTML might be good. The only issue I see is if you plan additional scanning features... 🤷🏻‍♀️

[zachleat]

Renaming this from AutoCopy to HtmlRelativeCopy (via mode: "html-relative"). Earlier comments edited to reflect new changes!

[zachleat]

I finally got around to testing this and had been banging my head on it for like 30 minutes before I thought to check back on this thread and see you're going in a different direction 😅

Couldn't figure out why AutoCopyPlugin was undefined.

Oh no! I’m sorry!

"auto" isn't especially specific, and boxes in the API if you want to make a new style in the future (hopefully not, but you never know). The way I'm seeing this mode is... files are statically analyzed from HTML only, right? It feels like a name that reflects the static analysis of HTML might be good. The only issue I see is if you plan additional scanning features... 🤷🏻‍♀️

I took your suggestion and settled on the html-relative copy name—thanks for the feedback!

[zachleat]

Shipping with v3.0.1-alpha.1