Allow sections to be configured in nav

[athal7]

In order to achieve top-level sections (e.g. to utilize material navigation tabs), I need to either:

• use this plugin but restructure all of my docs based on those sections
• use the native mkdocs nav functionality, and miss out on the good features here including the spread operator for the "rest" of the pages

It would be great to be able to specify custom sections in the .pages file of the docs_dir, e.g.:

nav:
  - Vision:
    - principles.md
    - roadmap.md
  - People:
    - team.md
    - advisors.md
  - ...

[lukasgeiter]

Restructuring your docs actually sounds like a good idea to me. Can you help me understand why you don't want to go that route?
Of course I understand that there is some work involved, but I would think that it should be quite easy to move a few files into folders and update any links if necessary. Plus you'll end up with a better organized file structure.

[athal7]

Users have bookmarked some of the pages, and I’m not 100% sure this is the final organization, so I don’t want to setup redirects potentially multiple times

[athal7]

Looking at trying to implement this, I can see why there's some hesitation @lukasgeiter :). Some abstractions in the test setup around asserting section children have the section as the parent and some of the assumptions in MetaNavItem may make this request challenging to fulfill.

[lukasgeiter]

The implementation is only part of why I'm hesitant. Your request somewhat goes against the core idea of the .pages file. Which is configuring the navigation at the folder level.

I think a better idea for you might be to add support for an ... entry to nav in mkdocs.yml. I'll look into the feasibility of such a feature and get back to you soon.

[athal7]

good thinking, and thanks!

[lukasgeiter]

Good news! I did some quick tests and should be possible. Here's how it's going to work:

If a ... entry is present, the plugin generates a second navigation tree based off the file structure. All pages explicitly mentioned in nav are removed from this navigation tree before it is inserted in place of the ... entry.

It's going to take me a bit of time to properly implement and test this. I'll let you know once the release is out.

[lukasgeiter]

I've just released v2.4.0 with this feature. Check out the updated README for all the details.

[athal7]

Works great, thank you @lukasgeiter!