[FR] Extend "flat" to also work with dirs

[jaklan]

The new flat feature is great, but unfortunately it has some limitations:

1. The following one works as expected - under Project Name I get one, flat list of pages from docs/ and from all subdirs inside docs/.

   nav:
   - Projects:
    - Project Name:
       - ... | flat | projects/project-name/docs/**/*

   However - what If I don't want to flat subdirs? What I mean is - I would like to avoid Docs in nav, but I would like to preserve all the subdirs, so I get:

   • Projects/
   • Project Name/
     • Page 1
     • Page 2
     • Subdir/
     • Page 3

And of course the point is not to define all the subdirs manually, but to autogenerate it.

I tested 2 approaches:

• in the below scenario we only get Page 1 and Page 2; Subdir and Page 3 are not included at all.

  nav:
  - Projects:
   - Project Name:
      - ... | flat | projects/project-name/docs/*

• I tested both above variants with additional .pages file inside projects/project-name/docs/ with various combinations, i.a. with subdir specified explicitly:

  nav:
  - subdir
  - ...

  but it didn't have any impact on results - they were exactly the same as before.

2. Another issue I have is the usage of that new functionality within .pages files. I wanted to use such nav in main mkdocs.yml:

   nav:
   - ... | projects/**/*

   to automatically populate all the projects (actually in that example I don't need to specify nav at all to get the same result, but in real-life scenarios I just use it to define the proper order of nav tabs). It works great as it is, but of course then we have unwanted Docs in nav. My idea was to define .pages file in each project and specify there to flat the sub-structure to avoid Docs in nav.

I created such projects/project-name/.pages file then:

nav:
  - ... | flat | docs

but it doesn't work - I get exactly the same results as without the file, so Docs stays in nav. I did a few more tests:

• - ... | flat - the same result
• - ... | flat | docs/* - doesn't work at all, nothing is generated
• - docs | flat - returns an error: mkdocs_awesome_pages_plugin.navigation.NavEntryNotFound: Nav entry "docs | flat" not found.

As mentioned by @lukasgeiter in #36:

The feature was not designed to do anything more than flatten the list of remaining pages.

and that's the reason why it doesn't cover more complicated scenarios, when we actually need to work more with dirs than just pages. That FR is about extending the functionality of flat.

[lukasgeiter]

Thanks for the issue. Although I actually meant your original comment that lists your requirements. I have no intention of extending flat. It's a very temporary solution and will be replaced with something else entirely.

[jaklan]

Also my proposal of the potential solution - if we allow the following syntax: - some_dir | flat or - ... | flat | some_dir we would be able to handle both issues.

Ad. 1) Here we could go with such nav:

nav:
  - Projects:
     - Project Name:
        - projects/project-name/docs | flat

or

nav:
  - Projects:
     - Project Name:
        - ... | flat | projects/project-name/docs

The generated structure should look then this way:

• Projects/

  • Project Name/
  • Page 1
  • Page 2
  • Subdir/
    • Page 3

  so we avoid redundant Docs section in nav, but we keep the hierarchy of files and subdirs inside docs/ folder.

Ad. 2) Here we could also reuse the above approach then, so we would define such .pages file in projects/project-name/:

nav:
  - docs | flat
  - ...

or

nav:
  - ... | flat | docs
  - ...

In result we should get the same result as in 1), but with no need to specify the structure manually in mkdocs.yml.

This way we also shouldn't break nav definitions from .pages in deeper dirs, because the only thing we do is to move everything one dir up. If someone would like to move the structure e.g. 3 dirs up, they could just create 3 .pages file in each "unwanted" dir with the above syntax (to keep the approach of using .pages to manipulate nothing more than the exact level of hierarchy where it's located).

[jaklan]

@lukasgeiter I know, but actually that comment, and especially point 2), reflects my requirements better than original one 😉 (e.g. I mentioned then that I use - ... | projects/**/* as a workaround, but actually it turned out to be a real blessing for monorepo, because we don't have to touch mkdocs.yml at all anymore, the whole structure is generated automatically).

Sure, I see, I just haven't seen your comment before posting the above solution proposal. But well, maybe it would become some inspiration for the future implementation 😉

[jaklan]

Just one more comment for the full context - to achieve the result mentioned in point 1) with current capabilities, we need to do this:

nav:
  - Home: README.md
  - Projects:
    - Project Name:
      - ... | flat | projects/project-name/docs/*.md
      - Subdir:
        - ... | flat | projects/project-name/docs/subdir/*.md
      - Subdir2:
        - ... | flat | projects/project-name/docs/subdir2/*.md
        - Subsubdir:
          - ... | flat | projects/project-name/docs/subdir2/subsubdir/*.md

All above just to avoid Docs in nav. As you can see - it's almost impossible to maintain.