Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Navigation not in alphanumeric order (when pages config is automatic) #638
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:
Now when I build the docs the chapters won't be in the correct order.
The problem exists regardless of the theme.
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
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.
changed the title from
table of content elements not in alphanumeric order
Navigation not in alphanumeric order (when pages config is automatic)
Jun 17, 2015
Here is a test-repo to reproduce my 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.
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.
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
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.
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.
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.
referenced this issue
Jun 26, 2015
added a commit
Jun 27, 2015
Wrote a really crappy (but working) script for generating a human-sorted, title cased and auto numerated menu - https://gist.github.com/zamber/af5086cb9c097be5c002.