Call me collections

[parkr]

• Use Collections for data feature
• Allow us to read in collections
• Render collections
• TomDoc the sh*t outta this code
• Write docs
• Expose to Liquid via site.*

/cc @gjtorikian

Fixes #1941.

[parkr]

This compiles to:

collections: ["methods"]
render:
  methods: /methods/:subdir/:title:extname

Specifying the output URL only in one key rather than trying to clump things and over-complicate collections key.

Thoughts on this, @gjtorikian & @benbalter?

[gjtorikian]

It makes sense. The : notation leaves a bit to be desired. I think what bothers me is seeing it in such close succession: :title:extname. Is this the only possibility, or can another syntax be used?

[parkr]

@gjtorikian Other option is to do string interpolation:

render:
  methods: "/methods/#{subdir}/#{title}#{extname}"

Would just use ERB to inject the variable values and boom done.

Downside: inconsistent.

[benbalter]

Really like this. Two questions:

1. What's subdir?
2. Don't :'s in values bork YAML sans quotes?

[parkr]

1. :subdir is the subdirectory that contains the file, i.e. the folders b/w the collection folder and the file. E.g. jekyll is the subdir for _methods/jekyll/configuration.md.

[parkr]

shouldn't that be :path?

:path would include the filename.

And when would I want any configuration other than :path/:file:extension?

When I want to prefix all the files with something.

[benbalter]

When I want to prefix all the files with something.

Do you have an example that would be >= 20% of the use cases? Feels like an edge case to me that adds a lot of complexity and could be resolved by simply using a different naming pattern for the file.

[parkr]

So in the case of _methods/site/generate.md, what would you expect the output path to be?

[benbalter]

So options one, it's always /:collection_name/:path, unless you specify a permlink. Option two, you specify a permalink structure of /:collection/:path and get /methods/site/generator?

[parkr]

Yeah those are the options. The question is whether we should allow the user to specify. Maybe that's a 2.1.0 optimization. PUNT. 🏈

[parkr]

@penibelst What if I add this for layouts? Re: #2070

[doktorbro]

@parkr Sorry, I can’t judge if it solve the issue.

[benbalter]

The vision is to eventually 🐶food this for Pages and Posts, right? 😄

[benbalter]

May want to make notes in the docs that this is an experimental feature and that the API may likely change until the feature stabilizes. Can help manage expectations and give us a bit more flexibility around SemVer.

[parkr]

@benbalter Thank you times a million for reading through this and commenting. So freakin helpful.

The vision is to eventually 🐶food this for Pages and Posts, right?

ja, but I want to get an initial version out there. There are a larrrrge # of further questions in order to turn pages and posts into collections (like using the Page and Post classes) so I'd rather do that in a different PR.

[parkr]

@benbalter Do you think we should just send back the docs array instead of the label, too? It then behaves like site.posts:

{% for datafile in site.collections.data %}
  {{ datafile.foo }} {{ datafile.bar }}
{% endfor %}

[benbalter]

Let's not make things harder down the line, or build out a new design pattern.

I'd expose collections as a first class citizen like we do posts or pages, so a documents collection should live as site.documents and I should iterate through it just like I would site.posts or site.pages.

[parkr]

"a first class citizen"

so a documents collection should live as site.documents

I'm really weary of this in terms of configuration collisions or future features. What's so bad about namespacing them in site.collections?

[benbalter]

What's so bad about namespacing them in site.collections?

Because pages, posts, and data would be first-class citizens in Jekyll's eyes, but my collections would be a second class citizen (Not to mention, would make dogfooding 999x harder).

User is in control of both site config vars and collection names. Assuming that a collection name is plural, the potential collisions you're looking at are plugins, layouts, gems, which I'd argue, collections could just overwrite, as those three in particular are rarely access in userspace.

[parkr]

User is in control of both site config vars and collection names

Alright... this puts my mind at ease. My greatest worry about this is obviousness – will the user intuit access to these collections? If not, how can we get them as close as possible to just knowing that a given collection can be accessed in this way with this variable reference?

[benbalter]

Answering your question, and another advantage is education is easier. "Collections are just like posts or pages, but you choose what they're called". Behavior is identical to existing behavior, no new site.collections.foo design/interaction pattern to learn.

[benbalter]