Mismatches between explicit and extensionless layout declarations causes quirks when running eleventy with --serve

[noelforte]

Operating system

macOS Sonoma v14.2.1

Eleventy

2.0.1 (also reproducible on 3.0.0-alpha4)

Describe the bug

This bug was a nasty one to stumble upon and took me a while to pin down where it was stemming from. At first I thought it was a WebC issue, but it turns out it affects other template types too and is probably why extensionless layout support was intially removed. Nevertheless, I'm raising this issue and can also open a pull request on the documentation to document what I think may be a common pitfall.

The gist of this bug (or perhaps intended behavior) is that when template layout keys reference the same layout, but one file uses the extension explicitly and the other doesn't. While --serveing, the template that has the explicitly declared extension won't be rebuilt when changes are made unless the dev server is restarted.

UNLESS...there's a directory data file that defines the same layout with or without an extension, if there is, then the declaration of that layout blocks any file from being rebuilt that doesn't follow it's convention. In other words: once a directory data file is introduced that uses/doesn't use the file extension for a layout that sets the standard for all other files using the same layout. Furthermore, if there are files that are in a directory that don't have directory data files in them they can also be blocked from getting rebuilt.

Reproduction steps

I've included a reduced test case for anyone interested to play around with. Some things I've tried to get reproducible results (although some of these might be inaccurate, I don't know a lot about Eleventy's internals to guarantee whether this behavior aligns with what's expected)

1. Run eleventy --serve
2. Edit the nunjucks-layout.njk file
3. Observe that only the files with the .njk extension declared on the layouts (with and without directory data) get updated.
4. Moving the 2 markdown templates with frontmatter into their own folder prevents them from getting updated
5. Moving them into the root input directory causes the one that matches the directory data file to get updated
6. Removing the directory data file causes the one without the extension to not get updated

Expected behavior

Given the complexity of attempting to debug the behavior going on here when there's mismatched layout declarations, I'm not quite sure what the expected behavior should be. Perhaps an error warning that gets thrown if things are mismatched? Or maybe something added to the documentation that says that if you're mixing extensions vs extensionless layout definitions all bets are off when trying to determine why live reload isn't working.

Either way, being consistent with extensions in layouts vs leaving them out seems to be critical in order to get Eleventy to run correctly.

Reproduction URL

https://github.com/noelforte/11ty-webc-layouts-rtc

Screenshots

No response

[zachleat]

Did you see this? https://www.11ty.dev/docs/layouts/#omitting-the-layouts-file-extension

We did try to change this default at one point but it was too painful for folks.

[noelforte]

@zachleat Yep! I've gone through that part of the documentation and I understand that there's a difference in functionality when the template extension is dropped (matching all possible layouts, vs matching a single layout with an explicit file extension). What I didn't expect was that unexpected things can occur when 2 templates refer to a layout with and without the file extension, which I guess "It is ambiguous if you have multiple layout files with the same name and different extensions (e.g. mylayout.njk and mylayout.liquid)." sort of calls out?

In my case live-reload wasn't updating my pages after making a change and my fix was to go through my entire project and enforce consistent use of extensions in all my layouts. For good measure I also added eleventyConfig.setLayoutResolution(false); to my config.

I also tested the inverse: removing all extensions from layout calls and the live-reload issues also resolved themselves when doing things that way too. Maybe all that's needed is to supplement the part of the documentation quoted above with something like:

"Consistency is key! When referring to your layouts from a template, be sure to either always leave out the file extension or always include it and/or disable layout resolution to enforce specific file extension use. Otherwise, Eleventy can get confused when building the layout map which can lead to things not working properly when --watching or --serveing."