Feature request: do not render subdirectory as section

[madjxatw]

If this is a thing about MkDocs internal and has no way to address without change to MkDocs, that's OK, I will open a feature request in its repo.

Sections are defined by using the following syntax in mkdocs.yml, which has nothing to do with any subdirectory inside docs

nav:
  - Section1:
    - file1.md
  - Section2:
    - file2.md

The navigation will be rendered like:

Section1
  title of file1.md
Section 2
  title of file2.md

MkDocs doesn't allow specifying directory or using globbing, this is why awesome-plugin comes. With awesome-plugin in use and the following directory structure:

docs/ 
  |__ .pages
  |__ index.md
  |__ section1/
           |__ .pages
           |__ index.md
           |__ section2/
                    |__ .pages
                    |__ index.md
                    |__ ...

docs/.pages contains:

nav:
  - index.md
  - section1

docs/section1/.pages contains:

nav:
  - index.md
  - section2

docs/secton1/section2/.pages contains:

nav:
  - index.md

We only need index files in the navigation, all non-index Markdown files will get linked from inside index files. After build, we get the navigation list like:

title of docs/index.md
Section1
  title of docs/section1/index.md
  Section2
    title of docs/section1/section2/index.md

My feature request is that I don' t need those section markers, it should look like:

title of docs/index.md
  title of docs/section1/index.md
    title of docs/section1/section2/index.md

Why does this feature make sense? Suppose:

• title of docs/index.md is "Chapter1"
• title of docs/section1/index.md is "Section1"
• title of docs/section1/section2/index.md is "Section2"

With those section markers there, it looks like:

Chapter1
  Section1
    Section1
  Section2
    Section2

A bit weird, right? That's why those section markers should be removed. But what if those who don't use index files like this and they really need the section markers for grouping. I think it could be done like:

nav:
  - index.md
  - Section 1:
     - section1

Only if an explicit section is given, then produce that section item in the nav.

Of course, this could be tweaked in theme templates, but I personally think taking subdirectories as section items automatically is a bad idea because you never know how your users want their directory to be handled. Instead of tweaking each theme, it should be addressed inside the navigation generator itself.

Anyway, appreciating for developing this plugin as it really helps!

[lukasgeiter]

To clarify, you want the entries to be displayed nested, right? Like this:

• Chapter
  • Section 1
  • Section 2

---

If that's the case, my plugin won't be of much help. In the current MkDocs model, pages cannot have children and sections are only for grouping pages. A proper solution needs to be implemented in themes and ideally also MkDocs itself.

One thing you can try is the mkdocs-section-index plugin. It patches the theme's template to combine the section header with an index.md entry. Not the most elegant approach, but it seems like the feature might be included in mkdocs-material natively at some point.

I haven't tested this, but with the plugin you should be able to use the following nav config in mkdocs.yml and get what you want:

nav:
  - Chapter1:
    - index.md # gets merged with the section header
    - Section1:
      - section1/index.md # gets merged with the section header
      - section1/section2/index.md

[madjxatw]

They are not necessary to be displayed nested, I could place a meta attribute like index: true in all index files and tweak the theme a little bit to have theme nested. It would be great if the removal of the section entries could be easily done in your plugin. Thanks a lot for providing the useful information, I will spend time trying out the mkdocs-section-index plugin.

[lukasgeiter]

Okay if they don't have to be nested, you achieve this by simply listing them manually in mkdocs.yml:

nav:
  - index.md
  - section1/index.md
  - section1/section2/index.md

I realize that this might a bit tedious if you have many files. I've been thinking about implementing a new feature in my plugin that would extend the existing globbing capabilities by an option to essentially flatten the matching subtree into a list of pages. With this you would only need a single entry that matches all index.md files and it would produce the same navigation as the config shown above.

Let me know if something like this would be useful to you.

[madjxatw]

Sorry for the late response, it would be great if there is an option for those you mentioned above– flattening the matching subtree into a list of pages.

[squidfunk]

Not the most elegant approach, but it seems like the feature might be included in mkdocs-material natively at some point.

Insiders 1.17.0 just landed, which adds native support for section index pages 😉

[kuangp]

Hi, I wanted to also request the flattening subtree feature. It would help us place all docs under 2 different directories under one title section as a flat list.

[jaklan]

+1 for that, the only thing I'm seriously missing in the plugin!

[jaklan]

Another example - I use the plugin for monorepo, because it's much more flexible than mkdocs-monorepo-plugin. I would like to specify such nav in main mkdocs.yml:

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

docs/projects directory is symlinked to projects, so I can discover docs in sub-projects without copying anything.

That wouldn't really work, because that's what you get in the navigation:

What I do now as a workaround is:

nav:
  - ... | **/*.md

and use hide option in .pages wherever I need, but it has 2 drawbacks:

• you have to introduce .pages files to the repo
• you can't modify the nav structure, so you end up with sub-sections which normally you would skip, e.g. docs (so you would have only Projects -> Project Name -> [list of pages]):

@lukasgeiter what do you think about it? Or maybe you have an idea for some workaround until it's included in the plugin?

[jaklan]

One more note - actually in docs the last example of using globs look this way:

But... it doesn't work this way - in reality we get:

• Introductions:
  • Introduction
  • Folder:
  • Introduction
• ...

So that's exactly the issue I described above.

PS mkdocs-literate-nav plugin provides proper implementation of that.

[lukasgeiter]

@jaklan Thanks for explaining your use case. I have the feeling that the flattening the navigation items might not be the best option to address your needs. Although a better solution will take some time, so I'll try to implement that in the meantime.

---

Thanks for pointing out the problem with the example in the docs. The depicted result can be achieved by enabling collapse_single_pages, but I have to agree that it's a bit misleading.

[jaklan]

@lukasgeiter that would be great! For that reason I almost switched to mkdocs-literate-nav, but unfortunately there's another bug in that plugin which made it impossible for me: https://github.com/oprypin/mkdocs-literate-nav/issues/6

And that's also interesting note for the potential implementation in mkdocs-awesome-pages - the current syntax of nav in .pages located in sub-dirs only allow for filtering the files located at given level, no deeper, so the allocation of responsibilities is pretty clear - you want to filter files / folders from dir/? Put .pages there. You want to filter files / folders from dir/subdir/? You need another .pages at that level.

But if we want to introduce the functionality of inlining pages from some deeper dir into the given one - the filtering has to be done bottom-up, not top-down, because we could get a similar issue like in mkdocs-literate-nav.

[madjxatw]

Glad to see this issue is still being updated and thanks for all the efforts, but I've switched to Sphinx + myst_parser as mkdocs itself has no intention to relieve the pain of using it...

[lukasgeiter]

Flattening is now available in version 2.6.0! Here's how that looks like:

nav:
  - Regular:
      - ... | flat
  - With Pattern:
      - ... | flat | *.md

[jaklan]

@lukasgeiter great to hear! I've already started to test it and unfortunately I have some issues:

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

It's really great to have that feature added, because it definitely handles a part of use-cases, but unfortunately - still not mine 😕

[lukasgeiter]

@jaklan The feature was not designed to do anything more than flatten the list of remaining pages. With the current approach, I'm at the limit of what I can do while keeping things maintainable. Unfortunately that means it will take some time until your use-case is properly supported.

Would you mind creating a new issue with your requirements? (copy pasting your initial comment from here should be enough)