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

Update Read The Docs theme with upstream #588

Closed
d0ugal opened this issue Jun 3, 2015 · 68 comments · Fixed by #1594
Closed

Update Read The Docs theme with upstream #588

d0ugal opened this issue Jun 3, 2015 · 68 comments · Fixed by #1594

Comments

@d0ugal
Copy link
Member

@d0ugal d0ugal commented Jun 3, 2015

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.

@d0ugal d0ugal added this to the 0.14.0 milestone Jun 3, 2015
@ProfYaffle
Copy link
Contributor

@ProfYaffle ProfYaffle commented Jun 3, 2015

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

@d0ugal d0ugal commented Jun 3, 2015

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

@waylan
Copy link
Member

@waylan waylan commented Jun 3, 2015

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

@tterrag1098 tterrag1098 commented Jul 21, 2015

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

@w3guy
Copy link

@w3guy w3guy commented Aug 1, 2015

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

@ergonlogic
Copy link

@ergonlogic ergonlogic commented Aug 11, 2015

👍 for the Aegir Project docs too

@damonregan
Copy link

@damonregan damonregan commented Oct 7, 2015

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

@thenitai thenitai commented Oct 28, 2015

👍

@dmehra
Copy link

@dmehra dmehra commented Dec 1, 2015

Another vote for collapsible nav option!

@ghost
Copy link

@ghost ghost commented Dec 11, 2015

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

@thenitai thenitai commented Dec 12, 2015

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

@brianjking brianjking commented Dec 29, 2015

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

@thenitai thenitai commented Dec 31, 2015

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

@d0ugal d0ugal removed this from the 0.15.0 milestone Jan 14, 2016
@d0ugal d0ugal removed this from the 0.15.0 milestone Jan 14, 2016
@marcelstoer
Copy link

@marcelstoer marcelstoer commented Jan 22, 2016

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.

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 mentioned this issue May 5, 2017
@aldanor
Copy link

@aldanor aldanor commented Jul 26, 2017

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

@waylan waylan commented Jul 26, 2017

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

@cjsheets
Copy link

@cjsheets cjsheets commented Nov 4, 2017

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.

Example

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

@bastianeicher bastianeicher commented Sep 23, 2018

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 waylan closed this in #1594 Sep 27, 2018
waylan added a commit that referenced this issue Sep 27, 2018
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.
@waylan
Copy link
Member

@waylan waylan commented Sep 27, 2018

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

@cjsheets cjsheets commented Sep 28, 2018

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

@NateZimmer NateZimmer commented May 14, 2019

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

@xgaia xgaia commented Jan 24, 2020

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

@waylan
Copy link
Member

@waylan waylan commented Jan 24, 2020

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

@mkdocs mkdocs locked as resolved and limited conversation to collaborators Jan 24, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.