New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
CptLausebaer opened this Issue Jun 17, 2015 · 14 comments

Comments

Projects
None yet
6 participants
@CptLausebaer

CptLausebaer commented Jun 17, 2015

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

This comment has been minimized.

Member

d0ugal commented Jun 17, 2015

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

@facelessuser

This comment has been minimized.

Contributor

facelessuser commented Jun 17, 2015

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

This comment has been minimized.

Member

d0ugal commented Jun 17, 2015

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.

@d0ugal d0ugal changed the title from table of content elements not in alphanumeric order to Navigation not in alphanumeric order (when pages config is automatic) Jun 17, 2015

@d0ugal d0ugal added the Enhancement label Jun 17, 2015

@CptLausebaer

This comment has been minimized.

CptLausebaer commented Jun 17, 2015

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

image to display the issue:
mkdocs_screenshot_nav

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

This comment has been minimized.

Member

d0ugal commented Jun 17, 2015

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 comment has been minimized.

Member

d0ugal commented Jun 17, 2015

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

@d0ugal

This comment has been minimized.

Member

d0ugal commented Jun 17, 2015

@waylan

This comment has been minimized.

Member

waylan commented Jun 17, 2015

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

This comment has been minimized.

Contributor

ProfYaffle commented Jun 17, 2015

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

This comment has been minimized.

Member

d0ugal commented Jun 17, 2015

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

This comment has been minimized.

Member

d0ugal commented Jun 17, 2015

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 d0ugal added Bug and removed Enhancement labels Jun 17, 2015

@d0ugal

This comment has been minimized.

Member

d0ugal commented Jun 17, 2015

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

This comment has been minimized.

Member

waylan commented Jun 17, 2015

I can live with that.

waylan added a commit to waylan/mkdocs that referenced this issue Jun 27, 2015

Ensure consistent ordering of auto-populated pages.
Both files and directories should be sorted to ensure consistent ordering of
pages in the menus across builds and systems. Turns out to be a simple fix.
As `os.walk` provides a reference to the list of dirs it uses internally,
we can modify that list in place and it will use the modified list.

While this may not give proper alphanumeric ordering for all languages,
it goes ensure consistent ordering. For more control over ordering,
it is expected that a plugin could be used once that API becomes available.

Fixes mkdocs#638.

@d0ugal d0ugal closed this in #660 Jun 27, 2015

@zamber

This comment has been minimized.

zamber commented Sep 18, 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment