Update Read The Docs theme with upstream

[d0ugal]

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.

[ProfYaffle]

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!

[d0ugal]

It might make sense, yes. I've been pondering how to do that in a nice way.

[waylan]

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.

[tterrag1098]

👍 for this, would be very nice for the Forge docs project :)

[w3guy]

Sorry fo hijacking this thread, what version of MkDocs is Readthedoc running @d0ugal ? i can see build failing 'cos of older folder structure.

[ergonlogic]

👍 for the Aegir Project docs too

[damonregan]

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.

[thenitai]

👍

[dmehra]

Another vote for collapsible nav option!

[ghost]

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.

[thenitai]

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]

@d0ugal @thenitai Any idea if there's a way to manually implement such a feature of the sphinx RTD theme with Mkdocs as it stands today? Thanks!

[thenitai]

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

[marcelstoer]

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.

[aldanor]

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?

[waylan]

@aldanor, a877aae addresses the underlying structure. The CSS just needs updating, which controls how it looks.

[cjsheets]

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.

[bastianeicher]

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 menu.js and style.cs in your docs directory and reference them from mkdocs.yml:

extra_css: [style.css]
extra_javascript: [menu.js]

You can see the result at: https://0install.github.io/docs/

[waylan]

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.

[cjsheets]

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 😃

[NateZimmer]

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

[xgaia]

Hello everyone! Is there a release date for the 1.1 release? I'm interested in the dropdown menu functionality.

[waylan]

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:

1. Provide fixes (PRs) for the issues listed in Milestone 1.1. When those all get fixed (especially Fix mkdocs theme inheritance #1865), then we can release 1.1. If this gets done, I'll find the time to review the PRs and, when they are completed, do the release.
2. Backport all of the bug fixes listed in the Release Notes for version 1.1 (specifically only the items which start with "Bugfix: ...") to the 1.0 branch. All of the relevant commits can be included in one PR for this. If this gets done, I'll find the time to do a 1.0.5 release with the bug fixes (including the fix for this issue).

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.