Custom template languages and "Tried to use templateContent too early" errors.

[johnridesabike]

I'm working on a custom template language, and my site kept failing to compile due to "Tried to use templateContent too early" errors. This was puzzling, because a very similar version of the site would compile just fine with a different template language, and I couldn't figure out why templateContent was possibly being used too "early."

I finally figured it out, I think. Here is my understanding of what was happening:

• In my custom language extension's compile function, it catches exceptions, logs their messages, and then throws another exception.
• When templateContent is first accessed, it isn't rendered yet and throws this error. Eleventy will catch this error and then try to render the templateContent field.
• Because I was catching the "templateContent too early" exception, and throwing my own, this broke Eleventy.

Once I started re-throwing the same exception that I caught, then the site suddenly started working again. (This is fine, since I had no real reason to throw a different exception, anyway.)

There is currently no documentation about this behavior, and the exception's message doesn't communicate what's going wrong. My suggestion is: can we add something to the "Custom template extension" documentation page, warning people not to catch exceptions that come from Eleventy, perhaps even mentioning this situation as a "common pitfall" (if it's common)?

Perhaps there's a better way to implement this templateContent feature that doesn't leak unexpected behavior, but I think we should at least document the existing details.

[zachleat]

Good call-out!

Related: #1615 and #975

[zachleat]

#975 is shipping with 2.0.0-canary.20