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.