useLayouts option for Custom template syntax allows opt-out of Eleventy Layouts for a template type

[rustycoat]

Operating system

Debian Testing

Eleventy

2.0.0

Describe the bug

Per instructions on the website and in various github issues, default layouts can be provided at the directory level (including the root via various methods). Unfortunately, these layouts are not specified to relevant file types and will wrap ALL 'templates' with the layout template, including assets that intend to generate css or javascript (or other new applications, like processing images).

Reproduction steps

1. Set dir.input to 'src', create 'src' directory and add two files: 'layout.njk' and 'asset.scss'. Make sure layout.njk outputs {{ content | safe }}.
2. Set the global layout either via src/src.json or via config object to 'layout.njk'.
3. Use addTemplateFormats and addExtension to implement sass preprocessing as shown on the website.
4. Run eleventy build and view the contents of asset.scss to see that the contents of layout.njk have been wrapped around it, with asset.scss taking the place of {{ content | safe }}.

Expected behavior

Expect that SCSS files will not be treated as an object with a 'layout'.

Reproduction URL

No response

Screenshots

No response

[rustycoat]

Unfortunately eleventy's genericity makes it sort of blind to basic structural patterns in its most dominant use case (websites).

On the positive side, this blindness allows novel extensions of its processing pipeline -- which is why SASS is recommended on the website to be added in the same manner as html templates. But I think it's being misapplied in these cases, because the tools were obviously designed for html templating (with things like page resources and a layout field). This is clear in the statement on the website "Note also that the data is not used in the above example. This is the full Eleventy data cascade and may be more useful in other templating languages."

The only reasonably-simple fix I can see is a first-class division between assets, templates, and data. Data has already been seperated with addDataExtension. An addAssetExtension could do the same for assets.

In the case of 'templates', we are looking at something that has both 'layout' and 'data'. In the case of 'data', we have only data and no output file. But with assets, we will need to have an output file, and possibly data, but no layout.

Ideally Eleventy would allow us to simply define based on configuration which of the the following three functions it should perform on which extensions/files/globs:

1. Applying a cascading layout engine (templates)
2. Sourcing data into our cascading data tree (templates, data)
3. Creating an output with or without preprocessing/transformation in the pipeline (templates, assets)

Of course, I'm guessing to do this in a more clear and reusable way would break the API and also creep into something too general-purpose (which is already how the problem began). So addAssetExtension is probably a good enough solution :).

In the short term, there are several user-level hacks when a directory-wide (or root directory) layout default is good for content creators:

1. Put assets that should be co-located in a subdirectory of the given directory with a directory data file that sets 'layout' back to 'null'. If needed also set the permalink structure to remove the subdirectory in the site build. (clean, but required to be implemented each time this pattern shows up in the source tree)
2. In a base layout that all other layouts inherit from (works in Nunjucks) add logic to check the page url and not output anything other than {{ content }} if it's not an extension that generates html output. (icky, but implement once).

[zachleat]

These are great points, I’m going to milestone this for 3.0

[zachleat]

Related #2854

[zachleat]

I think the most straightforward path here is to add a useLayouts option for custom template syntax.

https://www.11ty.dev/docs/languages/custom/

Built-in template syntax will have this enabled and custom engines will have this enabled by default for the 3.0 release.

Whether or not the outputFileExtension option is set to html might make a better fallback, but I’m going to play it safe for now and we’ll revisit in a future major version.

Setting useLayouts: false will also preclude data from layout files for the Data Cascade for these templates: https://www.11ty.dev/docs/data-cascade/

I also filed an additional enhancement issue to opt-out entirely from the Data Cascade for a custom template engine too, if you’d like to subscribe to track future progress: #3336

useLayouts will ship in 3.0.0-alpha.14, thank you!

[zachleat]

Temporary docs preview URL deploying here: https://11ty-website-git-v3-11ty.vercel.app/docs/languages/custom/#uselayouts