Follow

Keep Up to Date with the Most Important News

By pressing the Subscribe button, you confirm that you have read and are agreeing to our Privacy Policy and Terms of Use
Contact

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

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.

MEDevel.com: Open-source for Healthcare and Education

Collecting and validating open-source software for healthcare, education, enterprise, development, medical imaging, medical records, and digital pathology.

Visit Medevel

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.

>Solution :

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

I think there are two ways to 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.
Add a comment

Leave a Reply

Keep Up to Date with the Most Important News

By pressing the Subscribe button, you confirm that you have read and are agreeing to our Privacy Policy and Terms of Use

Discover more from Dev solutions

Subscribe now to keep reading and get access to the full archive.

Continue reading