Can I influence the order of directories and pages in mkdocs/mkdocs-material manually?

Question

In this example, I have a book-like documentation and it has three chapters:

• Introduction
• Basic Use
• Advanced Use

These would go into separate directories (with sub-pages each ...). The file layout would look like this:

doc/
  advanced-use/
  basic-use/
  intro/

By default, mkdocs and mkdocs-material will order alphabetically, so chapters would end up in the order shown in the file layout above.

Things I know about, but would like to avoid:

• The nav setting in mkdocs.yml: I specifically wish to avoid setting nav, because then I would have to manually list every single page.
• Including a prefix on the directory's or page's filename: If I did this and later re-arranged something, all existing links would break. I also don't want a bunch of numbers in my URLs, so ordering by filename is off the table for me.

I am looking for a way similar to jekyll's/just-the-docs' nav_order variable, which can be specified in the frontmatter metadata.

Answer 1

I found a plugin to mkdocs that does exactly what I was looking for:

mkdocs-nav-weight

You add a weight property to your frontmatter, and it takes care of sorting the navigation. It even keeps "previous"/"next" intact. It also deals with section index pages out of the box.

Answer 2

The code to build the navigation (see here) suggests that there is currently no way of doing this.

I think there are two ways moving forward:

1. You build some external tool to generate the nav setting to list all the files the way you want them.
2. Open an Issue / PR at the mkdocs repo and built the wanted functionality into mkdocs itself.