[FEATURE] `flat n` - How to include nested folders correctly?

VladimirFokow commented 4 months ago

Please advise me on the correct way to solve this issue. 🙏 If impossible - I suggest a feature that would solve it.

I think it's currently impossible to do all of this at once:

put the topic A first in the nav
rename the topic A nav section (e.g. to "TOPIC A" - all in capital letters)
and make the top level index.md page (that the users automatically start on) be inside of topic A nav section

Let's say we have the following structure of our docs:

We have the unrelated top-level topics (topicA, c_topic, b_topic, etc.)
inside of each topic: we can have pages, as well as sub-topics (which can have further nesting)

docs/

└─  index.md

└─ topicA/
   ├─ a1.md  # topic has pages
   └─ a2.md
   └─ topicA_subA/  # and sub-topics
      └─ a_suba1.md
      └─ next_levels/  # (further nesting is possible)
         └─ ...
   └─ topicA_subB/
      └─ a_subb1.md
      └─ a_subb2.md

└─ c_topic/
   ...  # etc.

└─ b_topic/
   ...  # etc.

I want to have "TOPIC A" like this, and let everything else stay automatic.

TOPIC A
- index
- a1
- a2
- topicA_subA/
  - a_suba1
  - next_levels/
    - ...
- topicA_subB/
  - a_subb1
  - a_subb2

B TOPIC
...

C TOPIC
...

(I'm using Material's navigation tabs)

Concrete use case:

- "TOPIC A" is our "Home" tab, which should be first. It contains several pages, and we want index.md also inside of it

$${\color{orange}The \space problem}$$

What I've tried and why there is a problem: 0. (default) If `mkdocs.yml` has: ```yml nav: - ... ``` then "TOPIC A" isn't the first in order. But it has all the desired sub-structure. --- 1. Attempt 1: If `mkdocs.yml` has: ```yml nav: - TOPIC A: - ... | topicA/** - ... ``` then there is an unnecessary "topicA" folder: ```md TOPIC A - topicA # this folder is unnecessary - a1 - a2 - topicA_subA/ - a_suba1 - next_levels/ - ... - topicA_subB/ - a_subb1 - a_subb2 ... ``` --- 2. Attempt 2: Trying to address the problem in attempt 1 - to remove the unnecessary folder, we can try adding `flat`: ```yml nav: - TOPIC A: - ... | flat | topicA/** - ... ``` but then topic A loses **all** of its subdirectories: ```md TOPIC A - a1 - a2 - a_suba1 # subtopic folders are lost - a_subb1 - a_subb2 ... ``` --- 3. Attempt 3: You can set the order of topics like this (and their sub-folder structure will be preserved ( 🎉) : ```yml nav: - index.md - ... | topicA/** - ... ``` BUT then: - can't rename the tab, e.g. to "TOPIC A" - can't include 'index.md' inside of topic A

$${\color{orange}The \space manual \space workaround}$$

This workaround is too manual and unacceptable. Here is how: Move all the sub-folders out to the top level, and specify each of them manually. Change the file structure to this: ``` docs/ └─ index.md └─ topicA/ ├─ a1.md # here have only files (no sub-directories) └─ a2.md └─ topicA_subA/ # move each sub-topic to the top-level └─ a_suba1.md └─ next_levels/ └─ ... └─ topicA_subB/ └─ a_subb1.md └─ a_subb2.md └─ c_topic/ ... # etc. └─ b_topic/ ... # etc. ``` Then `mkdocs.yml` can be like this: ```yml nav: - TOPIC A: - index.md - ... | topicA_subA/** # set each sub-topic manually! - ... | topicA_subB/** - ... | flat | topicA/** # files flattened - ... ``` - this preserves nesting within the sub-topics - files are flattened not to have the "topicA" directory around them Is this the only way?... - This method requires an extreme amount of manual work and maintenance.. - It also greatly reduces readability - the sub-topics clutter the top-level space, and don't live inside their respective topic which makes it hard to maintain

$${\color{lightgreen}The \space solution?}$$

An idea how this should be achieved (if there are no better methods) : add an optional parameter `n` to `flat`: `flat n` - if `n > 0`: leave a max. of `n` nesting levels in the end - if `n < 0`: remove a max. of `abs(n)`outer nesting levels (The default behavior with no parameter is `n=1`) (`n=0` is interpreted as `n=1`) (I say max. in case there are not enough nesting layers to leave / remove)
For example, `flat 1` -- the resulting folder has max. 1 nesting level `flat 2` -- the resulting folder has max. 2 nesting levels `flat -1` -- the resulting folder has all the nesting levels except the outer-most one `flat -2` -- the resulting folder has all the nesting levels except the outer-most two ...
So the problem above can be solved with: `mkdocs.yml` has: ```yml nav: - TOPIC A: - ... | flat -1 | topicA/** # removes only 1 top level of nesting - ... ``` Would result in: ```md TOPIC A - a1 - a2 - topicA_subA/ - a_suba1 - next_levels/ - ... - topicA_subB/ - a_subb1 - a_subb2 ... ``` (desired example with `index.md` also included) ```yml nav: - TOPIC A: - my index: index.md - ... | flat -1 | topicA/** - ... ```

VladimirFokow commented 4 months ago

You can try this example here: https://github.com/VladimirFokow/example_for_issue99

VladimirFokow commented 4 months ago

maybe this is related? https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/issues/53#issuecomment-947105853 Would the proposed solution there solve this?

lukasgeiter commented 4 months ago

If I understood correctly, you just want to re-order the top-level sections/directories. In that case, this should do the trick:

nav:
  - topicA
  - ...

VladimirFokow commented 4 months ago

thanks for the reply @lukasgeiter !

Unfortunately your suggestion doesn't work at all... (I've attached an example repo ready to try it)

Instead, this would put topicA first:

nav:
  - ... | topicA/**
  - ...

But it's not flexible enough. I think it's currently impossible to do all of this at once:

put the topic A first in the nav
rename the topic A nav section (e.g. to "TOPIC A", as in my examples above - in all capital letters)
and make the top level index.md page (that the users automatically start on) be inside of topic A nav section

lukasgeiter commented 4 months ago

It works, if you place it in docs/.pages. But I believe you're right - it's currently not possible to satisfy all your criteria without adjusting your file structure.

VladimirFokow commented 4 months ago

ah, I see; added this approach to the example repo

lukasgeiter / mkdocs-awesome-pages-plugin