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

[VladimirFokow]

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:

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:

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

then there is an unnecessary "topicA" folder:

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:

nav:
  - TOPIC A: 
    - ... | flat | topicA/**
  - ...

but then topic A loses all of its subdirectories:

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 ( 🎉) :

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:

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:

nav:
  - TOPIC A: 
    - ... | flat -1 | topicA/**  # removes only 1 top level of nesting
  - ...

Would result in:

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

...

(desired example with index.md also included)

nav:
  - TOPIC A: 
    - my index: index.md
    - ... | flat -1 | topicA/**
  - ...

[VladimirFokow]

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

[VladimirFokow]

maybe this is related? #53 (comment)
Would the proposed solution there solve this?

[lukasgeiter]

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]

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]

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]

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