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.

[waylan]

As a reminder, while doing this, we should probably incorporate #608.

Also, #316 may be related. although I expect titles defined in the frontmatter would be ignored for nested index pages.

[Seneral]

I didn't know you have to follow a structure such as that from YAML so strictly, so your solution seems like a good way to go.
And yeah, automatically looking for files which are not specified doesn't sound too well, not only it seems impossible due to folder structure but if the user would intend to have the index file used like this, it would be no problem adding a line...

Not dealbreaking but sure a nice feature to have:) Definitely awaiting it!

[waylan]

I just pushed a PR for this at #1042. So see how it's used, I've added an about/index.md page to MkDoc's own documentation (which actually makes a lot of sense) in the PR.

The problem is that, while the About item in the nav links to the index page, the clicks are interrupted to display/hide the dropdown list of children, so you don't ever to to the page from the nav. The page is still accessible via the next/previous links, but there's not much point in adding the feature until the navigation issue is resolved. We need to way to differentiate between showing/hiding the dropdown and following the link. Not sure of the best way forward here.

i realize we could just stop the click form being interrupted (presumably via JavaScript), but the new page would start to load before the user would have an opportunity to interact with the dropdown. We need two separate actions and a way to differentiate them.

[waylan]

I just took a look at the readthedocs theme to update it and there was no easy obvious way to update the template. Sure, its possible, but it would require a lot of refactoring and would probably mean some reworking of the CSS as well. So I got curious and looked at how RTD does it for their Sphinx projects and I noticed that they don't use index pages anywhere except the home page in the root directory.

If the much larger RTD community does not support or need this feature, I'm wondering if perhaps we should not try to either. The issue is only every encountered when users try to include index pages in sub-directories. If we simply documented that that is not supported, that would be it. To be clear, that it not necessarily my personal preference and it feels like the easy way out, but I'm wondering if it is the right one.

[Seneral]

What about either a seperate part of the button for opening the dropdown (like an arrow at the right) or opening the dropdown by hovering over the parent for 1/4 sec?
Don't know how hard it would be to implement for you though...

[waylan]

@Seneral those may be valid options. My point is that we need to make that decision.

However, hover is a bad idea as that doesn't work on mobile devices. The dropdown needs to happen on click.

[waylan]

I think I have a working solution in #1042. If those of you who need this could check it out and let me know if this will meet your needs, that would be appreciated.

[Radiergummi]

Is there any news on this? Right now, my navigation is horrible:

...all the while, my source repository is neatly nested:

├── dokumentation
│   ├── index.md
│   ├── backend-api
│   │   └── index.md
│   ├── frontend-anwendung
│   │   ├── index.md
│   │   ├── api-abstraktion.md
│   │   ├── authentifizierung.md
│   │   └── code-styleguide.md
│   └── server
│       ├── index.md
│       ├── backup
│       │   ├── index.md
│       │   └── konfiguration
│       │       ├── backup.sh
│       │       ├── config
│       │       └── mysqldump-backup.cnf
│       ├── konfiguration
│       │   ├── index.md
│       │   ├── ssh
│       │   │   ├── ssh_config
│       │   │   └── sshd_config

// ... and so on

It would be really nice to have an arbitrarily deeply nested structure for the pages. In our case, we provide base configuration files for server services alongside the descriptionary pages, so I don't just want to throw everything in a single folder. These docs will be read on the Git web frontend, on the rendered docs page and from the file system directly, so proper nesting is a must.

[waylan]

@Radiergummi development stalled on this in #1042. After developing a "working solution" all sorts of problems were discovered with it. Feel free to read the discussion there for the details. Most notable to you is that the readthedocs theme will never be able to support the feature as that theme is a clone of the Sphinx theme of the same name and the Sphinx theme doesn't support the feature either.

[Radiergummi]

@waylan okay, thank you. In the meantime, I've switched to the material theme and wrote a simple bash script build step that iterates the tree and puts the files in an order that makes more sense to mkdocs.

Though I think this'd make sense, even if it means forking the readthedocs theme. It didn't change much (at least visually) over the last years IIRC.
By the way, what I read from #1042 it sounds like there is confusion on how to correctly determine the current group index page, right? Wouldn't that be possible by iterating each directory recursively, having a special $index property maybe. If there is a matching file found in the current directory - say index.md, readme.md or home.md - set this page to $index. Themes could then either link the category header to that index page if they support it or append it to the category, using the first H1 found in the content as a title. Alternatively, you could replace $index with the category name aka. directory name - supporting themes would notice there's a category and a page with the same name and react accordingly, legacy themes would put it into the category like any other page.

Maybe I'm completely off track, please kindly ignore me then, I didn't use mkdocs before 😄

[waylan]

@Radiergummi we have working code in #1042. The problem is that the existing themes don't work well with the underlying structure. For example, the readthedocs theme is a direct clone of the Sphinx theme of the same name (which we will not be extending). There is the possibility that some themes would support the feature and others would not. So do we want to add a feature which doesn't get universal support across themes? The answer to that question is the hold-up.

The end of the conversation then detours into various different ways we might be able to represent the structure to make it easier for themes to implement the entire feature within the theme (rather than programmatically). None of those suggestions had yet been explored as we have been working on higher priority items.

However, I should note that my work on the pages refactor has resulted in pages being sorted so that the index page always sorts to the top in a directory. This would guarantee that the first child of any directory would always be the index file and that might be enough for a theme to implement the feature.

[Radiergummi]

@waylan I understand where you're coming from, nevertheless themes have different feature sets anyway, and I'm sure authors would pick the change up soon.
However this'll play out, thank you for your extensive answer and mkdocs!