Feature request: do not render subdirectory as section

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]

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.

[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 😉