Zola: It is not clear how to sort section.pages by the default sorting set up by the section's sort_by

[kurji]

Documentation issue

Summary

In my template, I have {% for subsection in section.pages %} but that results in unsorted pages (different order every reload/change, Zola 0.9.0).

The documentation says:

// Pages directly in this section, sorted if asked
pages: Array<Pages>;

but how do I "ask"? I don't want to hardcode in the theme HTML file the type of sorting, I would have thought that would come from the page (e.g. its sort_by = "weight" directive). I trawled through the Tera documentation and it seems to indicate I should use a | filter but I have no idea which one to use.

Proposed solution

It would be excellent if the documentation mentioned how to sort by the default section sorting, to sort by weight, or to sort in general.

Even better, it would be better if the array was sorted in the default way as specified by the section sort_by. That was my expected behaviour and I've already spent half an hour trying to figure out why the order kept changing (I kept modifying the weight values and inspecting my CSS, but I believe it is the HTML coming out in the wrong order).

[Keats]

cc @photong

[photong]

I'll clear up the wording for the current docs next maybe next week. I have some ideas for a "Reference" section that will explain each setting in detail with many examples.

[photong]

Is the text below clear?

// Pages directly in this section. By default, the pages are not sorted. Please set the "sorted_by"
// variable in the _index.md file of the corresponding section to "date" or "weight" for sorting by
// date and weight, respectively.
pages: Array;

[kurji]

That is clearer, so would make a good improvement :)

Upon closer inspection, it appears that the original problem I listed in the description is that I thought setting sort_by once in the root _index.md would work.

I have a directory structure like so:

• _index.md
• folder/_index.md
• folder/other1.md
• folder/other2.md
• folder/other3.md

I had the sort_by = "weight" in the root _index.md but not in folder/_index.md and apparently it doesn't sort unless I also specify it in that folder/_index.md. Is the sort_by not inherited? I feel as though I read that somewhere, but now I can't find it.

It would be ideal if this was inherited, or at least documented clearly that it's not. It seems tedious to have to duplicate the sort_by for every single section in my site...

Note that the documentation also says:

Sorting Subsections

Sorting sections is a bit less flexible: sections are always sorted by weight, and do not have any variables that point to the next heavier/lighter sections.

This does not seem to be the case, as it defaults to "none". Should this part of the documentation therefore be removed?

It also says:

Note: Unlike pages, permalinks will not be used to break ties between equally weighted sections. Thus, if the weight variable for your section is not set (or if it is set in a way that produces ties), then your sections will be sorted in random order. Moreover, that order is determined at build time and will change with each site rebuild. Thus, if there is any chance that you will iterate over your sections, you should always assign them weight.

If this is still true, it would be ideal for it to be fixed to be consistent with pages; otherwise, it might be worth adding a warning that appears in the console output when the weight is the same for sections.

[photong]

Thanks for the suggestions. I'll take a look at this next week (swamped with work currently).

[Keats]

Ping @photong are you still interested in doing that?