- Sponsor
-
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
Update Read The Docs theme with upstream #588
Comments
Does this make more or less sense if combined with the 'first page heading appears in the ToC unless you suppress it' issue? Not sure they're related, but they are in my mind as I had to do the latter to try to address the length of the ToC, which is what this issue also addresses. But - yes, please, optional or not! |
It might make sense, yes. I've been pondering how to do that in a nice way. |
This sounds like it would go in the template. What if it was in a block and/or include so it could be overridden by custom themes, etc. That strictly wouldn't require a setting, but given it makes more sense to have it off by default I can see you you might go that route... What if it was extra css and/or extra JavaScript files that users could copy into their project if they want it--no setting required. At some point, I expect that various third parties will start to create and make available such things to add additional features. Might be nice to start a list of what's available and make this the first item on the list. That way, it is not included by default (no unnecessary bandwidth is used) but can be easily added. |
👍 for this, would be very nice for the Forge docs project :) |
Sorry fo hijacking this thread, what version of MkDocs is Readthedoc running @d0ugal ? i can see build failing 'cos of older folder structure. |
👍 for the Aegir Project docs too |
I too would like this collapsible navigation behavior seen at http://pip.readthedocs.org/en/stable/user_guide/ for my project documentation: http://sandboxdocs.readthedocs.org where the TOC is frustratingly long and looses focus when looking at pages at the bottom of the TOC (e.g., System APIs). If the user clicks a System API page (e.g., Overview), the TOC goes back to the top of the page and the user can no longer see the System APIs section they were interested in reading. |
👍 |
Another vote for collapsible nav option! |
I would also like to have an option for a collapsible navigation menu. Showing all items at once looks totally chaotic with a large number of pages. |
Yes, totally confusing. We moved all our documentation over but showing all menus at once is chaotic. While we are at it, worse is that when you click on a menu it jumps all the way up, thus the user looses focus. |
@brianjking I'm sure there is a way to do it within the template somehow. I just haven't found the time to look into it, but this is definitely a must have. The RTD themes look nice on their side for other projects (not made with mkdocs) so I'm sure it is just a template issue. I can look into it, but would need a guide or alike... |
Just spent quite some time comparing my MkDocs setup with other projects (which are obviously Sphinx-based) because I also want those collapsible navigation items. Pity it's not supported. |
Collapsable headings and other niceties aside, the real show-stopper with the RTD theme is the lack support for nested headings in TOC. So if you have a document with a lot of headings from H1-H6, they will all get dumped inline into a big mess of links. Is there an easy way to support that? |
For anyone interested, I setup a version of the mkdocs ReadTheDocs theme with collapsible sidebar support. You can see the theme in action here, or see installation instructions. The theme is stable though still under development. Still needs a number of refinements and I don't know if it supports all MkDocs file structures. As waylan mentioned (here and in other issues), there are differences between how mkdocs and readthedocs parse files/headings so a direct clone of ReadTheDocs behavior would require changes to the mkdocs core. I didn't want to do that because I don't want to maintain a fork of the entire project. For my purposes, a RTD-style theme that collapses the sidebar to a manageable size is sufficient. |
Fixes mkdocs#1142 for mkdocs theme. RTD theme will be addressed with mkdocs#588.
I put together a few lines of JavaScript that collapse menu sub-sections in MkDocs's ReadTheDocs theme. It also auto-scroll the menu to the active page. function collapse(tree) {
$(tree).children("span.caption-text").addClass("expandable");
$(tree).children("ul.subnav").hide();
}
function expand(tree) {
$(tree).children("span.caption-text").removeClass("expandable");
$(tree).children("ul.subnav").show();
}
// Collapse all sub-menus except the containing the current page
$("li.toctree-l1").each(function() {
if ($(this).find(".current").length == 0) {
collapse(this);
}
});
// Scroll to the current page
$("nav").scrollTop($("a.current").offset().top - 128);
// Expand sub-menu on click and collapse all other sub-menus
$("span.caption-text").click(function(event) {
if ($(event.target).hasClass("expandable")) {
collapse("li.toctree-l1");
expand($(event.target).parent());
}
}); (https://github.com/0install/docs/blob/master/docs/menu.js) It requires the following additional CSS: span.expandable { cursor:pointer; } You can put these into files named extra_css: [style.css]
extra_javascript: [menu.js] You can see the result at: https://0install.github.io/docs/ |
Fixes #588 and fixes #1374. # Some implementation notes: ## `include_homepage_in_sidebar` setting Note that the homepage is always linked from the site_name above the search box. Therefore it does not need to also be in the nav tree. In the upstream Sphinx theme, this is controlled when defining the toctree. However, Sphinx has a separate setting for identifying the "homepage". In MkDocs the homepage is identified as the first item in the `nav`. Therefore, without this setting you can't exclude the homepage from the sidebar like you can in Sphinx. With this setting we get feature parity. ## Nested sections This output is a little weird as the section title is a link that does nothing when you click it. You need to click the `+` to expand the submenu. But that is what the upstream theme requires to work.
FYI to everyone who wants this, #1594 was just merged and will be available in the 1.1 release coming soon. Note that the native collapsible nav is fully supported and your various third-party hacks may break things with that release. I would suggest testing things now. Any feedback would be appreciated (please open a new issue to report problems). A list of new theme specific settings can be found here. |
Awesome! I'll check it out. If it looks like "rtd dropdown"s behavior is covered by the native collapsible nav support, I'll probably just depreciate the theme and advise to use the new feature 😃 |
So its 5/2019 and this still isn't out. How does one use mkdocs 1.1? Will mkdocs 1.1 ever be released? Current release is 1.04 |
Hello everyone! Is there a release date for the 1.1 release? I'm interested in the dropdown menu functionality. |
I work on MkDocs as a volunteer in my spare time, which is very short supply. I don't have time to do all of the work required to properly prepare a release. If anyone wants to help you have two options:
However, until either of those two things happen, there will be no new releases. If I find some unexpected free time in the future, I'll do the work, but I don't expect to anytime soon. Any help you can provide would be appreciated. |
The Upstream RTD theme has added some nice features for collapsing the navigation. You can see an example in pip Sphinx documentation. We have some users that could benifit from this, like GlusterFS, as they have many pages.
As a side, I happen to think that it is a negative update for smaller projects so I could be tempted to make this optional. Perhaps with an extra: config value like "extra: collapsable_nav: True" which would be specific to this theme? It could either remove the feature totally or expand by default.
The text was updated successfully, but these errors were encountered: