Eleventy: Better understanding collections

[watershed]

I'm just getting started with Eleventy. This is not so much an issue as a desire to understand the collections concept and its default parameters better than I've managed to glean from the documentation.

In essence, what factors cause a content file to be added to a custom collection (as opposed to the all one)?

Here's why I am asking.

I have a directory in a clone of eleventy-base-blog which I'll summarise like this:

    episodes.json -- {"tags": ["episodes"]}
    index.md -- layout: layouts/episodes.njk   tags: nav   navtitle: Episodes
    episode-1.md -- tags: episodes
    episode-2.md -- tags: episodes

And in episodes.njk:

layout: layouts/base.njk
templateClass: section
---
{{ content | safe }}
{% set postslist = collections.episodes | head(-3) %}
{% include "postslist.njk" %}

With this setup, my expectation was that index.md would _not_ be added to the episodes collection, because it is not tagged with episodes. But it is.

I've figured I can exclude it with eleventyExcludeFromCollections: true, but I don't understand why I have to. The documentation implies that tags applied in front matter are the trigger, but evidently that is not the only thing.

---

In closing, I know I am only getting started and I'm loving the simplicity of Eleventy, but I feel the docs don't provide enough perspective. They dive straight into 'here's how to do this specific thing'.

[kleinfreund]

The data directory file episodes.json makes alle documents inside its parent directory part of the episodes collection. In this example, the front matter values in episode-1.md and episode-2.md are superfluous. If you remove the tags field from the data directory file and keep the front matter like you’ve shown, the index.md document would only be part of the nav collection.

---

Regarding your point about the documentation: I’m not too happy with Eleventy’s documentation. I’d love to see a Getting started-style guide like Vue.js has: https://vuejs.org/v2/guide. Currently, I find it very hard to find in the documentation exactly what I look for. That problem is very apparent for newcomers as they usually don’t know the terms they have to look out for.

[kleinfreund]

One more thing: Maybe it’s easiest for your to move the index.md file out of the episodes directory (and probably name it something like episodes-index.md) and then assign to it permalink: episodes in its front matter. This way, you can keep the episodes.json file as it is and remove the tags field from the individual episodes.

[watershed]

Thanks so much Philipp. Is what you have pointed out in the documentation somewhere, or are we just supposed to somehow know?

I'm glad you share my perspective on the docs.

[kleinfreund]

Indeed, the documentation on collections does not cover this. I suppose it was written before the data directory files could be used like this and hasn’t been updated accordingly. I will file an issue for the Eleventy documentation regarding this.

[watershed]

Thanks also for your 'one more thing'.

I like to think I'm pretty good at grokking things, and I'm prepared to doggedly work through things until I do. I feel stupid when I just can't see the wood for the trees.

[kleinfreund]

You have nothing to blame yourself for. Tools for development (like Eleventy is) always (probably always) come with their own cognitive baggage (e.g. existing or new terminology). Without knowing before what options exist and how exactly the things are called you’re dealing with, it’s very hard to move forward. We can do better in making Eleventy more approachable and simple to grasp. Improving its documentation is hugely important to achieve that.

In short: A powerful tool has no potential without its users ability to understand it.

[watershed]

Thanks. Re your last point: https://twitter.com/schofeld/status/1125035729153921025.

[zachleat]

Appreciate all of this feedback, y’all. Issues like these are _how_ we know what to improve.

Is it okay to close this issue? Looks like we have https://github.com/11ty/11ty.io/issues/129 and https://github.com/11ty/11ty.io/pull/132 ongoing to improve the docs—let’s track progress over there. Would love your feedback @watershed after https://github.com/11ty/11ty.io/pull/132 is merged—can you subscribe to that issue?