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

Question

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

Opened this issue 7 months ago · 6 comments

VladimirFokow commented 7 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:

(default) If mkdocs.yml has:

nav:
  - ...

then "TOPIC A" isn't the first in order. But it has all the desired sub-structure.

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

...

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

...

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/**
  - ...

Answer 1 · 2024-02-17T15:19:27.000Z

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

Answer 2 · 2024-02-17T15:33:24.000Z

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

Answer 3 · 2024-03-04T06:48:02.000Z

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
  - ...

Answer 4 · 2024-03-04T10:42:50.000Z

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

Answer 5 · 2024-03-09T13:44:30.000Z

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.

Answer 6 · 2024-03-09T15:53:24.000Z

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