Allow sections to be configured in `nav`

lukasgeiter / mkdocs-awesome-pages-plugin

An MkDocs plugin that simplifies configuring page titles and their order

MIT License

453 stars 35 forks source link

Allow sections to be configured in `nav` #30

Closed athal7 closed 3 years ago

athal7 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

good thinking, and thanks!

lukasgeiter commented 3 years ago

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 commented 3 years ago

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

athal7 commented 3 years ago

Works great, thank you @lukasgeiter!