_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)

[coolshaurya]

@zachleat I think what @edwardhorsford meant by all templates is all the layout templates since what comes to your mind when you think about 'templates' is what eleventy calls 'layout templates' , IMHO.

[kleinfreund]

@zachleat To be clear, my question about what the advantages of a dedicated includes directory are was out of curiosity.

To summarize, a static site generator processes some input files into output files while (optionally) using a set of files which influence this transformation process, but which are itself not being transformed into output files. In other words: These files need to be exposed to Eleventy in a that stops them from being transformed. This mechanism currently is the includes directory (same applies to data directories).

Now as for the core of this issue: confusion. If I understand things correctly, the confusion arises due to the slightly fuzzy naming includes in relation to its purpose.

I believe @edwardhorsford’s point is that Eleventy uses includes as an umbrella for includes and templates of all sorts whereas other statis site generators would distinquish between these. For example, Jekyll has an _includes and a _layouts directory.

[edwardhorsford]

@kleinfreund is right, though my background is in node / express (as a designer, I should say), not static site generators.

I'm used to includes being a subset of templates or views. For me, eleventy is reversing that terminology - includes are the superset, and templates the subset.

Similarly, the Eleventyone base blog (which I started from) has what I'll call partials in the first level, and page templates one level deeper. I've always done it the reverse - page templates / views, then a folder inside that for partials.

[edwardhorsford]

@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?

Because the eleventy config calls it that. It's what the docs refer to as the place to store all template content.

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?

My ideal structure would probably be:

templates
- base-template.njk
- another-page-template.njk
- includes
     - header.njk
     - footer.njk
pages
- apage.md
- anotherpage.md
assets

Two things are different here - my templates folder is at the same level as my input folder.

And my templates folder contains a folder called 'includes' that has partials / macros. Naming wise it's a bit off, as I've had to tell eleventy that my "includes" dir is templates.

The only real issue there is that eleventy is using a name that I've traditionally used to mean something slightly different.
...

[kleinfreund]

Is there maybe a name (neither includes nor templates) that the describes the files in this directory better? For example, resources. A resource is something that is used in the greater context. I’m just thinking out loud here as I can’t come up with a better word.

If I had to choose, I woud say "templates" better describes what we mean here than "includes".

[zachleat]

Would love additional information on the definition of template here: 11ty/11ty-website#24

[jevets]

To me, _includes clearly implies that its child files won't be output to the _site directory, whether it's a template, a partial, a page template/view/layout, a chunk of content specific to a single page or view, or a directory housing reusable component's files — be them HTML based or something else completely.

Just my vote / two cents: I prefer _includes so that Eleventy can continue to avoid imposing any kind of layout/template/view/partial paradigm prescription or opinion, especially since 11ty already avoids prescribing a single templating language.

I organize my layouts, partials, views, templates, components, etc. within _includes depending on the project, especially when porting over an existing site.

[zachleat]

Circling back here, there are a few things that have changed since this discussion:

• Eleventy added an optional layouts directory.
• Eleventy allows you to use an empty string for the includes directory (allowing includes throughout).
• Seems like one of the main benefits to having a dedicated Eleventy _includes directory (rather than making everything relative) is that Eleventy doesn’t process these files. But you can use globs in your .eleventyignore file to do this too, see addPreprocessor Configuration API method to Ignore Files and simplify "Draft" templates #188 (comment)

After making some changes to the docs after re-reading this issue, I’m going to close this for now. If anyone would like to add additional notes and points of confusion to this, please feel free!