Ordering folders

[DannyBen]

Is there a way to specify folder order?

So far, I found only the order page config, and the SUMMARY.md option (here) for manual sorting (which I wish to avoid).

I was unable to make a simple structure of files (two in the root, and two folders with two files each) order as expected.

I have tried just numbers on the pages, alpha, semver - nothing seems to yield results that are desired and intuitive to write.

Ideally - I would want to:

• Set the order of folders and root files somehow - in the config maybe? Or a separate order.yml?
• Set some numeric or alpha on each page, to order it in that particular folder
• Have the order behave so that all pages that have order directive appear before ones that don't - this way, we can just "nudge" pages like Welcome to appear before Installation by only giving order to the Welcome page.

This way, I think it will be manageable.

By the way, the SUMMARY.md option - which I prefer to avoid - does not seem to obey the icon directive, which feels like a bug. I also posted here with a YAML suggestion.

In addition, the it is very counter intuitive that the page order option is in fact reverse.... higher numbers should be last, not first... 1 before 2.

EDIT

Ok, I found out that I can do place order for a folder in index.yml - but anything with alpha or semver do not work as expected, and the fact that the numbers are reverse drive me nuts - spent the good portion of the day trying to sort 3 files...

[AndreyChechel]

Hi, thanks for the nice and detailed feedback about ordering.

Like you found out - a page order can be specified in a top-level front matter block. A folder order can be specified in a index.yml file nested into that folder.

Just to shed some light on how ordering is implemented internally:

1. First, all items (pages and folders) are sorted by order number (assuming 0 if no explicit number is assigned to the order config)
2. Items with semver specified are sorted in descending order. Those items are rendered right below order: 0 group
3. Then, items within the same group are sorted in the way that folders are always in the top
4. Finally, items within the same group are sorted A -> Z using their labels or order: alpha values

Below is a sample demonstrating how the rules above are applied:

100 : C (folder) <-- folders are always at the top within the same `order: <number>`
100 : D (folder) 
100 : B (page)
100 : E (page)

50  : any label, any type (file/folder)  <-- label/type doesn't matter since `order: 50` takes precedence

0   : A (folder) <-- again, folders are at the top within `order: 0`, then sorted by label
0   : Q (folder)
0   : A (page)
0   : Betta (page, any name, `order: Betta`) <-- `order: <alpha>` overrides a page/folder label 
0   : C (page)

v2.0 : any label <-- semver takes precedence within the semver group, so label value doesn't affect anything
v1.1 : any label
v1.0 : N (folder) <-- folders are at the top within `version: v1.0` group, then A -> Z
v1.0 : P (folder)
v1.0 : F (page)
v1.0 : H (page)
v0.9 : any label

-1   : any label <-- Negative values in `order: <number>` are rendered below the semver group
-2   : any label

Like it was mentioned order: 0 is assumed whenever order: <number> is not specified, e.g.:

• order: zetta means order: 0 and also override label with "zetta"

[AndreyChechel]

Posting this C# snippet for those who're more comfortable with reviewing a piece of code:

pages
    .OrderByDescending(x => x.OrderNumber)
    .ThenByDescending(x => x.OrderSemver is null)
    .ThenByDescending(x => x.OrderSemver)
    .ThenByDescending(x => x.IsFolder)
    .ThenBy(x => x.OrderAlpha ?? x.Label);

please note that for simplicity sake, the code above doesn't contain things like string comparison type, and a couple more steps like the ones related to API/Blog page ordering

[DannyBen]

Wow - this is the most complicated sorting logic that anyone has ever devised, ever... :)

Why on earth number or alpha ordering is descending? I am not kidding when I am saying that for the past several hours, I am trying to create the desired sort order of tiny (few folders, few files in each) site. I feel like I am dealing with double negative here: Order, in fact means "Reverse Order" so higher number, means lower order. The cognitive complexity is too high. Not to mention that I already need to add "gaps" between numbers, so I can insert new docs in the future.

The one thing I figured out that helps, is this:

For all the elements (dirs or files) in the same "level", I am using one set of numbers - for example, starting from 100, in steps of 5 downward.

So things on the root are in one series, and then when going into another folder, the first file there (except the index.md, since it is a part of the parent series) is also getting 100, and I am starting to count downwards from here.

This is the one and only way that seems to be working for me, and is even close to being intuitive.

I am curious as to why descending order was the go to choice. Was it the semver "newest version first"?

Also - if this is still open to be changed, I feel that:

1. Ordering must be ascending. Plain and simple.
2. There should be no special treatment for semver or anything - you sort by order number (integer or float), or by string, or - if not present - by the label.
3. If someone wants more control, sort by a simple order.yml as I proposed here

In any case - thanks for being open and responsive - with or without the sorting issues, retype seems to be hands down the best markdown-to-beautiful-site generator.

[geoffreymcgill]

1. Ordering must be ascending. Plain and simple.

I'm not convinced.

I will certainly add some clarification to our order docs and more example scenarios. I can see that the existing docs on the subject could be clearer.

Higher weight = higher priority = higher in the stack
0 = neutral (Retype will alpha order by default)
Lower weight (including a negative value) = lower priority = lower in the stack

10000
1000
100
10
0  <-- all pages with no order set, in this zone
-10
-100
-1000
-10000

The semver ordering is more of an edge case scenario that we wanted to support. From my perspective, it still seems useful and implemented correctly.

[geoffreymcgill]

By the way, the SUMMARY.md option - which I prefer to avoid - does not seem to obey the icon directive, which feels like a bug.

SUMMARY.md is supported by Retype to make it simple to upgrade from legacy generators. Several, including GitBook (when you export your project) only configure their navigation using SUMMARY.md, so we needed to support that configuration method.

And, I agree, configuring the nav structure using SUMMARY.md is to be avoided. That is the primary reason why we haven't documented the feature.

which feels like a bug.

Kinda. More of a "we have not implemented that feature yet". It's on our list to implement, and should be relatively easy, but it's a low(ish) priority. Squeaky wheel policy applies here and I will bump up the priority.

[DannyBen]

It's on our list to implement

Based on the fact that you mention you support SUMMARY.md as a legacy "compatibility" features that is discouraged - I would avoid implementing the icons or anything else in that regard. Having an order.yml - if such a feature will ever exist - would be far superior, and converting SUMMARY.md to order.yml should take no more than 5 minutes.

[geoffreymcgill]

We will be adding order.yml (or something like it). I will bump this feature request up in priority (give it a higher weight 😉).

[geoffreymcgill]

In addition, the it is very counter intuitive that the page order option is in fact reverse.... higher numbers should be last, not first... 1 before 2.

In Retype, a numerical order is essentially a priority or a weight.

Higher weight = higher priority = higher in the stack
0 = neutral (Retype will alpha order by default)
Lower weight (including a negative value) = lower priority = lower in the stack

Here's the scenario: You have a large quantity of pages in your project. Some have a manual order applied to move them higher in the navigation stack to give them more precedence. For instance, you want a Getting Started guide to be at the top of the nav as it's your highest priority item.

In your scenario, if order: 1 is higher than order: 2, then:

1. What order would you apply to the Getting Started page so it's at the top of the navigation stack?
2. Down the road, you add another high-priority page, let's call it Introduction, and want that page to be at the top of the nav. What order would you apply to this new page so it's now at the top of the navigation?
3. You have dozens of other pages. Some with a numerical order applied and some without. Regarding those pages with no order applied; where are they in the stack? I would assume at the bottom? and ordered by-alpha?
4. Down the road, you add another page, let's call it License, but this time you want to shove it to the bottom of the navigation stack. What numerical order value do you apply?

I'll take a crack at those answers with your position that order: 1 must be higher than order: 2. Please correct me if I'm wrong...

1. Getting Started is my highest priority page, so I set order: 1.
2. Introduction page is added, so:
   1. I open Getting Started and set it's set to order: 1.
   2. I revised Getting Started to order: 2
   3. Then I set order: 1 on the Introduction page. I have now modified two pages.
   4. Save, view the working website, yep it works!
   5. Or, another scenario is more likely
   6. Introduction is my highest priority page, so I set order: 1.
   7. Save, view the working website, it's not working. Getting Started is still above Introduction, but why 🤷.
   8. I open Getting Started and see order: 1 and revise to order: 2.
   9. Save, view the working website, yep it works!
3. All other pages rendered lower than Introduction and Getting Started.
4. License is added, so:
   1. I find and open the lowest page in the navigation, it's called Versioning (versioning.md).
   2. I see no order is set on Versioning.
   3. Scratches head. How to get License to the bottom of the stack?
   4. Setting order: zulu would be an option, but not ideal.
   5. How would negative order values work? Where order: -1 is the highest priority item at the bottom of the stack? Does that mean order: -1 would be higher than order: -2. Or, does order: -1 mean it should always be at the absolute bottom of the stack and order: -2 would be above order: -1?

You could maybe avoid modifying two pages by initially setting order: 10 on Getting Started, then when Introduction is added, you could set order: 5. But then you would have to know to set order: 10 on Getting Started from the beginning.

Currently with Retype, where order: 2 is higher than order: 1, the configuration flow of the above scenario would be:

1. Getting Started is my highest priority page, so I set order: 1000.
2. Introduction is added, so:
   1. I open Getting Started and see order: 1000
   2. I set order: 2000 on Introduction to move it higher ⬆️. I have now modified only one page (the page I'm adding).
   3. Save, view the working website, yep it works!
   4. Or, another scenario that is likely:
   5. I vaguely remember Getting Started has high a priority. Maybe it was 1000 or was it 500? I'm not sure but let's jack up Introduction to 2000 just to be sure.
   6. Save, view the working website, yep it works!
3. All other pages rendered lower than Introduction and Getting Started.
4. License is added, so:
   1. I find and open the lowest page in the navigation, it's called Versioning (versioning.md).
   2. I see no order is set on Versioning.
   3. I set order: -1000 on license.md, which moves this page to the bottom of the stack.
   4. Or, another scenario that is likely:
   5. I vaguely remember that all other pages had a positive order value, but I'm not 100% sure. Let's kick License way down ⬇️ to -1000 just to be sure. I have again modified only one page (the page I'm adding).
   6. Save, view the working website, yep it works!

Hope this helps.

[DannyBen]

Yes, thanks for taking the time to write this detailed description.

Now that I understand that this is a weight system by design, and not an ordering system, it makes more sense. I will try to just "bubble up" my pages / folders that are not naturally ordered, see if it sits better.

But, if this is the case, the argument should not be called order. It should be called priority or something like that (although I understand that changing it now will just break things for people for little reward).

Order is always considered ascending, unless specified otherwise.
I would also probably avoid the word weight in this regard, because heavy things go down not up.

[geoffreymcgill]

The docs for order have been improved.

Let me know if you feel anything in there needs further clarification or reworking. Or, feel free to also revise the docs yourself and send as a PR.