Skip to content
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

Closed
SvenDowideit opened this issue Apr 8, 2014 · 20 comments
Labels
Milestone

Comments

@SvenDowideit
Copy link

@SvenDowideit SvenDowideit commented Apr 8, 2014

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 d0ugal added the Enhancement label Oct 7, 2014
@d0ugal d0ugal added this to the 1.0.0 milestone Nov 28, 2014
@d0ugal
Copy link
Member

@d0ugal d0ugal commented Nov 28, 2014

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
Copy link
Member

@d0ugal d0ugal commented Nov 28, 2014

See #116 for some good discussion related to this.

@d0ugal d0ugal changed the title intermediate index.html generation Allow intermediate index.html pages for categories and create automatic index pages when not provided generation Jun 5, 2015
@philippeluickx
Copy link

@philippeluickx philippeluickx commented Aug 9, 2016

Any updates on this one?

@waylan
Copy link
Member

@waylan waylan commented Aug 9, 2016

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
Copy link

@philippeluickx philippeluickx commented Aug 9, 2016

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
Copy link
Member

@waylan waylan commented Aug 9, 2016

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
Copy link

@Seneral Seneral commented Aug 22, 2016

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
Copy link
Member

@waylan waylan commented Aug 22, 2016

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
Copy link
Member

@waylan waylan commented Aug 22, 2016

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
Copy link

@Seneral Seneral commented Aug 22, 2016

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 added a commit to waylan/mkdocs that referenced this issue Aug 29, 2016
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.
@waylan
Copy link
Member

@waylan waylan commented Aug 29, 2016

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
Copy link
Member

@waylan waylan commented Aug 30, 2016

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
Copy link

@Seneral Seneral commented Aug 31, 2016

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
Copy link
Member

@waylan waylan commented Aug 31, 2016

@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 added a commit to waylan/mkdocs that referenced this issue Nov 1, 2016
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.
waylan added a commit to waylan/mkdocs that referenced this issue Nov 2, 2016
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.
waylan added a commit to waylan/mkdocs that referenced this issue Nov 2, 2016
* 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).
waylan added a commit to waylan/mkdocs that referenced this issue Nov 2, 2016
@waylan
Copy link
Member

@waylan waylan commented Nov 2, 2016

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.

waylan added a commit to waylan/mkdocs that referenced this issue Mar 10, 2017
* 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).
waylan added a commit that referenced this issue Mar 11, 2017
* Fix a nested `<li>` bug.
* More closely replicate nesting of the Sphinx theme nav (related to #588).
* If sections headers ever get urls, this will support them (related to #73).
@waylan waylan added this to To Do in Refactor search. via automation Feb 5, 2018
@waylan waylan added this to To do in Pages Refactor via automation Feb 5, 2018
@waylan waylan removed this from To Do in Refactor search. Feb 5, 2018
@Radiergummi
Copy link

@Radiergummi Radiergummi commented May 1, 2018

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

bildschirmfoto 2018-05-01 um 10 25 46

...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
Copy link
Member

@waylan waylan commented May 1, 2018

@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
Copy link

@Radiergummi Radiergummi commented May 2, 2018

@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
Copy link
Member

@waylan waylan commented May 2, 2018

@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
Copy link

@Radiergummi Radiergummi commented May 7, 2018

@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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Linked pull requests

Successfully merging a pull request may close this issue.

6 participants
You can’t perform that action at this time.