[FEATURE] `flat n` - How to include nested folders correctly?
Opened this issue ยท 6 comments
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. ofn
nesting levels in the end - if
n < 0
: remove a max. ofabs(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/**
- ...
You can try this example here: https://github.com/VladimirFokow/example_for_issue99
maybe this is related? #53 (comment)
Would the proposed solution there solve this?
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
- ...
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
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.
ah, I see; added this approach to the example repo