Allow intermediate index.html pages for categories and create automatic index pages when not provided generation

[SvenDowideit]

Given a mkdocs.yaml like

pages:
- ['index.md', 'Home']
- ['user-guide/writing-your-docs.md', 'User Guide', 'Writing your docs']
- ['user-guide/styling-your-docs.md', 'User Guide', 'Styling your docs']
- ['user-guide/configuration.md', 'User Guide', 'Configuration']
- ['about/license.md', 'About', 'License']

I would like mkdocs to generate the non-menu-listed index.html files:

user-guide/index.html
about/index.html

without adding those pages to the previous next navigation. Interestingly, If you add - ['user-guide/index.md'] to the pages above, that new page is not added to a menu, but it is added to the nav :(.

I'm happy to add them to a cfg list and mark them as non-nav, or autogenerated (though automagical would be best). Ideally, these pages should list all the sub-pages.

(yes, I need to solve this, its not a 'would be nice')

[d0ugal]

I think this makes sense, in terms of discovery of the docs it seems reasonable that somebody would expect /user-gude/ (as per the example) to show something.

I've actually tried this on the Django Rest Framework docs before, I thought going from http://www.django-rest-framework.org/tutorial/quickstart/ to http://www.django-rest-framework.org/tutorial/ made sense but you get a 404. Seems obvious that it doesn't now I know the internals.

[d0ugal]

See #116 for some good discussion related to this.

[philippeluickx]

Any updates on this one?

[waylan]

Is this issue even relevant anymore? Since the pages config has been refactored for multi-level navigation (see #482), does the behavior described in this issue still exist?

[philippeluickx]

What I try to accomplish is that I can add a folder (not a file) and mkdocs will add the contents to the menu. A lot of issues related link to this one (which is still open).

Might be I am missing something, hence asking for an update.

[waylan]

I think this issue has been forget about. Perhaps we assumed the issue was resolved by the fix in #482. If it has, then it should be closed. If it has not, then it should remain open

To be clear, I don't know if #483 resolved this. I haven't had time to verify one way or another myself. Until then, I don't have a definitive answer unless someone else can verify it before I can get to it.

That said, it was assigned the 1.0.0 milestone which we are not working on yet (expected to be the next after 0.16.0), so even if the issue remains, it is currently not a high priority for us.

[Seneral]

I want to achieve something like this:

pages:
- 'index.md'
- Building Extensions: 'BuildingExtensions/index.md'
    - 'Custom Nodes': 'BuildingExtensions/CustomNodes.md'
    - 'Custom ConnectionTypes': 'BuildingExtensions/CustomConnectionTypes.md' 

So basically I can click on the parent to open an overview page and the subpages are in turn automatically expanded when hovering over the parent.
But currently this is the only way I know of to create an overview page:

pages:
- 'index.md'
- Building Extensions:
    - 'BuildingExtensions/index.md'
    - 'Custom Nodes': 'BuildingExtensions/CustomNodes.md'
    - 'Custom ConnectionTypes': 'BuildingExtensions/CustomConnectionTypes.md'

Which does show the index file when visiting */BuildingExtensions/ but is only accessible by a sub-item 'BuildingExtensions/Home' which is unintuitive IMO.
Unless there is a way to do this and I misunderstood this issue, it still persists...

[waylan]

Thanks @Seneral. That clearly defines the current situation and the problem with it. Unfortunately, your suggested solution won't work at that would be invalid YAML. Regardless, I think we can come up with something that works.

Perhaps if no title is defined for the index.md file, then that is used as the URL for the parent item in the nav. However, if a title is defined for the index.md, then we get the current behavior (the index is listed separately and the parent does not link to any page).

I was going to suggest that a parent nav item with no URL would assume to point to an index page if one existed, but the nested nav items do not need to be nested in the file system or even map to the same directories (the file structure could be arbitrary and completely different from the nav structure). Therefore, there is no way to know which sub-directory to look in for the index page.

I was curious how this got missed, and then I realized that the documentation for MkDocs does not actually use index pages for the nested nav items. Of course, we should support such a thing.