-
-
Notifications
You must be signed in to change notification settings - Fork 2.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Allow intermediate index.html pages for categories and create automatic index pages when not provided generation #73
Comments
I think this makes sense, in terms of discovery of the docs it seems reasonable that somebody would expect I've actually tried this on the Django Rest Framework docs before, I thought going from |
See #116 for some good discussion related to this. |
Any updates on this one? |
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? |
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. |
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. |
I want to achieve something like this:
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.
Which does show the index file when visiting */BuildingExtensions/ but is only accessible by a sub-item 'BuildingExtensions/Home' which is unintuitive IMO. |
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 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. |
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. Not dealbreaking but sure a nice feature to have:) Definitely awaiting it! |
If the first child is a Nav Header is a `index.md` page, then that page is assigned as the URL of the Header. The problem is that you can't axctually access it from the Nav as the lcick is unterupted to display/hide the dropdown list of children. Almost fixes mkdocs#73. Also need to update the readthedocs theme.
I just pushed a PR for this at #1042. So see how it's used, I've added an The problem is that, while the 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. |
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 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. |
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? |
@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. |
If the first child is a Nav Header is a `index.md` page, then that page is assigned as the URL of the Header. The problem is that you can't axctually access it from the Nav as the lcick is unterupted to display/hide the dropdown list of children. Almost fixes mkdocs#73. Also need to update the readthedocs theme.
If the first child in a Nav Header is a `index.md` page, then that page is assigned as the URL of the Header. Mkdocs theme updated to use Bootstrap's split button dropdown for Nav Headers with URLs. Almost fixes mkdocs#73. Also need to update the readthedocs theme.
* Fix a nested `<li>` bug. * Add support for section headers with links (fixes mkdocs#73). * More closely replicate nesting of the Sphinx theme nav (related to mkdocs#588).
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. |
* Fix a nested `<li>` bug. * More closely replicate nesting of the Sphinx theme nav (related to mkdocs#588). * If sections headers ever get urls, this will support them (related to mkdocs#73).
Is there any news on this? Right now, my navigation is horrible: ...all the while, my source repository is neatly nested:
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. |
@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. |
@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. Maybe I'm completely off track, please kindly ignore me then, I didn't use mkdocs before 😄 |
@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. |
@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. |
Given a
mkdocs.yaml
likeI would like mkdocs to generate the non-menu-listed index.html files:
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')
The text was updated successfully, but these errors were encountered: