_includes folder for templates ??

[coolshaurya]

The config page says -

DIRECTORY FOR INCLUDES

Controls the directory inside which the template includes/extends/partials/etc can be found.

Includes Directory
Object Key	dir.includes
Default	_includes
Valid Options	Any valid directory inside of dir.input
Command Line Override	None

While the templating page says -

This will look for a mylayout.njk Nunjucks template file in your _includes folder (_includes/mylayout.njk). You can use any template type in your layout—it doesn’t have to match the template type of the content. An ejs template can use a njk layout, for example.

There is a lot of confusion when we see these 2 together - they are contradicting.

the includes setting tin the config should be renamed to _templates or something as it causes a lot of confusion and the documentation should be updated in the relevant places.

[zachleat]

Can you elaborate more about why that's confusing? I don't see the contradiction but I'd like to learn. Thanks!

[kleinfreund]

What exactly is confusing about the the name "includes" and where is the documentation contradictory?

If you’re talking about templates not being something you include then this is only partially valid. My base template, I do not include anywhere, yet it resides in the includes directory. However, partial template are being included. Also, not everything in the includes directory is necessarily a template; hence, neither includes nor templates would be entirely fitting names.

[edwardhorsford]

I don't know if this is what @coolshaurya is talking about, but I also had a bit of confusion when starting.

I've previously thought of includes as snippets / small bits of content, not all templates as 11ty does.

Traditionally in other apps I've had a templates or views folder that has all my base templates, and inside this is an includes or partials folder that has snippets / includes / macros. For 11ty, 'includes' has a wider meaning.

For my own 11ty project, I've reversed it back to how I've done it previously. A templates directory with base templates, and that contains an includes directory for snippets.

The only remaining confusion is that in my eleventy.js config I have to have includes: "_templates" which isn't my actual includes folder, but the wider templates folder.

[coolshaurya]

@edwardhorsford exactly my point , it is a much better explanation than mine

@zachleat & @kleinfreund Sorry, my mistake - although the the statements are not contradictory they certainly cause confusion. The config page states that the includes folder is meant for template includes/partials while the layouts page instructs to to put the layout templates in the includes folder.

I am going to submit a PR which changes the config page to something like this -

The _includes_ folder is meant for templates and data in general like layout templates.

I think that would remove the confusion.

[coolshaurya]

PR done - PR 22 in 11ty/11ty.io

[kleinfreund]

I have a short question for you all: What is the advantage of having an includes directory in the first place?

[kleinfreund]

Some thoughts on what is the includes directory?

I’d say the includes directory contains a project’s layout templates, partial templates and other includes.

A layout template is self-contained meaning that you can use it as the layout for some content and after running Eleventy, getting a complete HTML document representing that content. As such a self-contained structure, a layout template is typically not included anywhere which creates the confusion of having them in the includes directory.

Partial templates are not self-contained. They’re meant to be included; for example, by using them in a layout template.

Other includes could be documents or assets like an SVG file. They can be included in templates as well. Otherwise, they would probably not be stored in the includes directory.

---

I can now see how this might be confusing. Also, I’m not convinced that the concept of a dedicated includes directory is necessary. Could Eleventy work without special-casing it? One would presumably need to take care of not creating output for includes/templates, but other than that? What is it used for?

[edwardhorsford]

@kleinfreund I'd say it includes all them too. I also keep my macros in there - which I guess are like shortcodes.

Also, I’m not convinced that the concept of a dedicated includes directory is necessary. Could Eleventy work without special-casing it? One would presumably need to take care of not creating output for includes/templates, but other than that? What is it used for?

I'm pro a dedicated folder.

Having a dedicated folder for views matches my previous experience of other apps - which I think would help other new starters too. I've generally worked on projects where you keep your content and your styling separate.

I presume it also helps that when including partials on a page, you only have to reference the file relative to the includes directory, not the src.

Other than that, knowing it won't output is good.

One thing I'm not convinced about - requiring it be a folder inside of the input directory. If I had my preference, I'd probably have it at the same level as the input directory.

[kleinfreund]

One thing I'm not convinced about - requiring it be a folder inside of the input directory. If I had my preference, I'd probably have it at the same level as the input directory.

I agree. I believe this is discussed elsewhere, though.

[zachleat]

@edwardhorsford I’m still not understanding what y’all are talking about, especially this comment: #268 (comment)

I've previously thought of includes as snippets / small bits of content, not all templates as 11ty does.

Hm? Why are includes all templates? What does all templates mean here?

Most of the rest of the comment made sense to me, until I got here:

The only remaining confusion is that in my eleventy.js config I have to have includes: "_templates" which isn't my actual includes folder, but the wider templates folder.

I had assumed _templates would be in your input directory? Do you have an example of what you’re talking about?

[zachleat]

One thing I'm not convinced about - requiring it be a folder inside of the input directory. If I had my preference, I'd probably have it at the same level as the input directory.

Related: #67

[zachleat]

Also related: #232

[zachleat]

@kleinfreund this is a very interesting idea:

I have a short question for you all: What is the advantage of having an includes directory in the first place?

I do want to make sure that an empty includes directory works here—I think you have said that it does?

I do think the main benefit of having an includes folder is that it’s automatically excluded from processing from Eleventy (a la .eleventyignore entries)