Navigation not in alphanumeric order (when pages config is automatic)

[CptLausebaer]

mkdocs Version:

0.14.0

Summary:

I have a problem with the table of content of my docs. I want that my chapters are in the correct order.

Steps To Reproduce:

In the docs folder there is the following structure:

• docs/
  • book/
    • Chapter 1/
      • something.md
    • Chapter 2/
      • something.md

...

Now when I build the docs the chapters won't be in the correct order.

The problem exists regardless of the theme.

Expected Results:

• book
  • Chapter 1
  • Chapter 2
  • Chapter 3
  • Chapter 4
  • Chapter 5
  • Chapter 6
  • Chapter 7
  • Chapter 8
  • Chapter 9
  • Chapter 10
  • Chapter 11
  • Chapter 12

Actual Results:

• book
  • Chapter 8
  • Chapter 6
  • Chapter 5
  • Chapter 2
  • Chapter 12
  • Chapter 9
  • Chapter 4
  • Chapter 7
  • Chapter 3
  • Chapter 1
  • Chapter 11
  • Chapter 10

[d0ugal]

Is the repo public? Can you show us something so we can reproduce it?

[facelessuser]

I've done stuff like this before. You can just break it up by numeric parts and string parts in a list and sort the list of lists instead of the list strings. That is of course if mkdocs wants to support a numeric sort.

Anyways, some quick and dirty code.

from itertools import groupby

text = [
   "Chapter 99",
   "Chapter 100",
   "Chapter 3",
   "Chapter 33",
   "Chapter 4"
]

digit_text = []

for t in text:
    final_text = []
    for digit, g in groupby(t, lambda x: x.isdigit()):
        val = "".join(g)
        final_text.append(int(val) if digit else val)
    digit_text.append(final_text)

digit_text.sort()

for t in digit_text:
    print(''.join([str(x) for x in t]))

#### Output ####
# Chapter 3
# Chapter 4
# Chapter 33
# Chapter 99
# Chapter 100

[d0ugal]

On a second reading, I understand. This isn't to do with the table of contents, it is regarding the navigation. Subtle but important different.

We don't sort the files of you don't provide a pages config. They are shown in whatever order your file system gives them to us.

[CptLausebaer]

Here is a test-repo to reproduce my issue:
https://github.com/CptLausebaer/test-mkdocs

image to display the issue:

I wasn't sure if table of contents is the right name of it, but I hope the image will show what I mean.
I mean the section on the left.

So the only way to achieve a alphanumeric order is to declare all files in the mkdocs.yml at the pages section?

[d0ugal]

So the only way to achieve a alphanumeric order is to declare all files in the mkdocs.yml at the pages section?

Yeah, that is the only way to do it at the moment.

I would be happy to sort it, it is easy to do for most cases but I have no idea how sorting will work in some languages like Chinese. However, I guess we could improve the situation for English etc. and it wouldn't be any worse for the rest.

[d0ugal]

This look interesting - https://github.com/jtauber/pyuca

[d0ugal]

This is where we need to sort it in MkDocs. https://github.com/mkdocs/mkdocs/blob/0.14.0/mkdocs/config/config_options.py#L393

[waylan]

My initial reaction is that it should be an error to assume that files should be sorted alphanumerically (or in any particular order). In some use cases alphanumeric sorting might be wrong. I think that if a user wants a specific order, then the only way to achieve that should be by explicitly defining that order in the pages section of the config as it works now.

If any sorting is added to the auto-populated pages, then I would suggest that it be turned off by default. Of course, what would require an additional setting to turn it on. And sorting should never run on a manually defined pages config (as it is now).

Alternatively, this could be addressed via the future Plugin API (see #206). Via a "post-config" hook (or whatever is would be called--after config is validated), a user could define their own sort function which would sort the pages in the config according to their needs.

That said, looking at the source code, is appears that there is sorting already of the files within a directory, but not of the directories which contain those files (see https://github.com/mkdocs/mkdocs/blob/0.14.0/mkdocs/config/config_options.py#L332). Given @CptLausebaer's file structure, he needs the directories to be sorted as well.

[ProfYaffle]

FWIW, I see no problem explicitly defining order. If you don't, where does "Table of Contents" come relative to "Index" relative to "Appendix A"? Is "Chapter 1" before or after "Introduction"?

Given that, it never even occurred to me to accept an as-it-came-from-disc order.

[d0ugal]

Yeah, I see value in sorting properly as it will provide a consistent order anywhere. Otherwise I guess it could randomly change over multiple builds and platforms.

[d0ugal]

I would guess that alphanumeric is the most sensible default choice. Users that need a specific ordering should define it themselves. The order as-it-came-from-disc isn't obvious and as @waylan pointed out, we already sort files but don't sort directories. So, I'd consider this a bug even. We should sort or not sort them both the same way.

[d0ugal]

So, initially, I think we should do the sort on directories like we do with files. We can then later look at improving this or perhaps making it optional - but I think any other sorting should be delegated to a plugin as that starts to get quite specific.

[waylan]

I can live with that.

[zamber]

Wrote a really crappy (but working) script for generating a human-sorted, title cased and auto numerated menu - https://gist.github.com/zamber/af5086cb9c097be5c002.

[trein]

I think this is still not completely fixed. This is the behaviour I'm getting:

Expected:

SECTION:
- Problem 1
- Problem 2
- Problem 3
- Problem 4
- Problem 5
- Problem 6
- Problem 7
- Problem 8
- Problem 9
- Problem 10

Actual:

SECTION:
- Problem 1
- Problem 10
- Problem 2
- Problem 3
- Problem 4
- Problem 5
- Problem 6
- Problem 7
- Problem 8
- Problem 9

[waylan]

@trein that is how alphanumeric ordering works. Each column is sorted from left to right. If you want those to be sorted differently, then you need to maintain the correct number of columns.

01
02
03
...
09
10

[trein]

@waylan So, I'm not questioning how alphanumeric ordering works. I'm just saying that the solution that was implemented does not do what was suggested originally. From the original post:

The problem exists regardless of the theme.

Expected Results:
* book
 - Chapter 1
 - Chapter 2
 - Chapter 3
 - Chapter 4
 - Chapter 5
 - Chapter 6
 - Chapter 7
 - Chapter 8
 - Chapter 9
 - Chapter 10
 - Chapter 11
 - Chapter 12

Actual Results:
* book
 - Chapter 8
 - Chapter 6
 - Chapter 5
 - Chapter 2
 - Chapter 12
 - Chapter 9
 - Chapter 4
 - Chapter 7
 - Chapter 3
 - Chapter 1
 - Chapter 11
 - Chapter 10

In the original post, it was not requested that you sorted the navigation in alphanumeric order (as you can see in Expected Results above).

[waylan]

@trein, if you read through the comments you can see the the target of the issue changed. Yes, you pinpointed the original request. However, this lead us to recognize that directories were not sorted at all. In the end, we considered the lack of sorting to be a bug, which was fixed. However, we rejected the suggestion to change the sorting algorithm used (see this comment).

[titpetric]

I know this is a closed (but yet, alive issue), but... wasn't there some option to use the .md page metadata for sorting? I have a distinct recollection of seeing weight in the metadata somewhere which was(? citation needed) used as a numeric sorting key. It may have been for pages only, and not folders?

[waylan]

@titpetric I have no recollection of any such feature. I suspect you are confusing this with a different project.

[titpetric]

Correct, apparently it was Hugo. I don't see a reason a weight: int couldn't be added to the .md metadata and used as the sorting key, especially if the alternative is to define nav sections in the mkdocs config and update them manually when writing new docs.

[Ark-kun]

Alas, the navigation is still not in alphanumeric order.
If you have the following file structure:

index.md
articles/article_001.md
...
articles/article_999.md
legal.md
privacy_policy.md
terms_of_service.md

then articles comes last despite starting with "a":

index
legal
privacy_policy
terms_of_service
articles/article_001.md
...
articles/article_999.md

I thought fixing this would be as easy as adding a small nav section to the mkdoc.yml, but it does not seem to support directories...

This does not work:

nav:
- index.md
- articles
- legal.md
- privacy_policy.md
- terms_of_service.md

It seems that the only way I can make mkdocs show the pages in order is to explicitly list each and every page which is a bit tedious.