[Jekyll] Working with Collections

[bernardodiasc]

Collections allow you to define a new type of document that behave like Pages or Posts do normally, but also have their own unique properties and namespace.

http://jekyllrb.com/docs/collections/

This is pretty awesome. Way better than use data yml with all indexes. BUT:

Collections support is unstable and may change This is an experimental feature and that the API may likely change until the feature stabilizes.

Well, manged to work in the last commit on this branch collections, but to work properly we need to wait Jekyll and GitHub apply this fix: https://github.com/jekyll/jekyll/issues/2346

I hope dont take too long, because is a better way to work with pages.

[johnpuddephatt]

because is a better way to work with pages.

I've had a look at the documentation on the Jekyll site and I'm slightly confused...

• can you clarify the benefit of using collections? from what I could see they mostly look useful if you wanted to define different content 'types' with different front matter.
• are you imagining that each top-level grouping in the navigation would be a different collection? how would this differ from just making each top-level grouping a different category?
• wouldn't the navigation still need to be constructed manually to keep things in the right order? Or would the order be handled by a front-matter value? again, wouldn't the same be possible using pages?

[bernardodiasc]

in short, collection works the same as now, but without the need to manualy build the navigation (this is a workaroud actualy). its just collection of pages in the core way.

with collections we dont need to worry about build the navigation. a contributor will just send the markdown file and that's it.

[johnpuddephatt]

Ok, that makes sense. You'll have to bear with me as I slowly get to know Jekyll!

I can see that collections might make the navigation simpler, and that having to manually update a navigation file is not ideal, but wouldn't we still need some way of defining the order of pages in the navigation?

[bernardodiasc]

No worries, I'm learning Jekyll too.

The ordering thing is something that I dont have answers yet, but I'm imagining at least 3 ways to do this if dont have any default way. Need to make some tests.

[johnpuddephatt]

I've been experimenting with a navigation tree driven by file structure. As it's trivial for the primary navigation to be hardcoded, I think what we're looking for is a secondary navigation that pulls in all pages below the current top-level directory.

The following will return all pages that meet this criteria, sorted by a value 'weight' that needs to be defined in the top matter. This allows pages to be given a custom order.

N.B. This assumes that content is grouped in folders situated within the root. current_array[0] and this_array[0] would need adjusting if this wasn't the case (e.g. to current_array[2] for the way this repository is current set up)

    {% assign pages = site.pages | sort:"weight"  %}
    {% assign current_array = page.url | remove_first: "/" | split:"/" %}
    {% assign current_section = current_array[0] %}
        <h3>{{ current_section | replace: '-',' ' | capitalize }}</h3>

    <ul>
        {% for p in pages %}
            {% assign this_array = p.url | remove_first: "/" | split:"/" %}
            {% assign this_section = this_array[0] %}
            {% if current_section == this_section %}
                <li>
                    <a {% if p.url == page.url %}class="active"{% endif %} href="{{ p.url }}">
                        {{ p.title }}
                    </a>
                </li>
            {% endif %}
        {% endfor %}
    </ul>

[bernardodiasc]

How can I test the code? Replacing the current navigation by this one had returned:

[johnpuddephatt]

Working fork here

I would have done this earlier but I was struggling to get GitHub pages working properly – it turns out that when you make a fork you need to make a commit to prompt the pages to be built.

[bernardodiasc]

Looks interesting. But dont you think this complicates a bit what can be simpler? (I'm trying to visualize the content yet, still in progress with the reading, lot "non-related-to-this-project" work to do)

[johnpuddephatt]

I think it keeps things quite simple – having navigation driven by a mix of front matter and the directory structure seems preferable to managing a static navigation file if it achieves the same results.

In what ways do you think it's complicated or could be simpler?

[bernardodiasc]

I mean, the result seems the same as collections, but collections is a core system thing.

[johnpuddephatt]

If collections can be made to work then I have no issue it being used, but I also don't think this approach is any more complicated or less of a core thing – it's just filtering site.pages based on the current URL which is fairly straightforward :)

[bernardodiasc]

I'm testing this loop here in a different project (its nice to see in different perspective), and its working very fine. Also good to manipulate. I think you we can go on with this approach you had suggested. Can you send it?

[johnpuddephatt]

:+1:

PR sent.

[bernardodiasc]

Closing this. The collection bug seems that it will take a while to be merged (Pr sent to Jekyll to fix this), and maybe take even more time to GHP implement it.

[bernardodiasc]

by the way @johnpuddephatt , is it possible with this structure to have navigation groups (in the vertical navigation, as had before) ?

[johnpuddephatt]

I think it's going to be tricky with any solution that doesn't rely on a manually defined navigation file (whether using pages or collections), however I believe it would be possible and could be achieved either based on file structure or on some sort of front matter 'grouping' variable.

That said, I think we should establish a definite need for it before attempting to implement it – the content structure proposed by @designermonkey had no need for it, for instance.

[bernardodiasc]

We'll need for sure.

[johnpuddephatt]

But surely we can't be sure because the content structure hasn't been planned?