Make it possible to collapse the primary sidebar on wide screens

[choldgraf]

Currently, our primary sidebar is always visible on wide screens. On mobile screens, it becomes an off-screen drawer, with a hamburger menu to open it:

However, I think many people would also appreciate being able to close the primary sidebar on laptop/wide screens as well. This would allow them to focus on the content if they want to read closely. It was a fairly well-requested feature in the book theme, and works like this:

Proposal

Two changes:

• Bring the functionality to add a hamburger menu to the article header. Clicking it will hide the sidebar. It would disappear as you scrolled down the screen.
• (optionally) Add a keyboard shortcut to collapse the primary sidebar.

[trallard]

I am +1 on adding a way to collapse the sidebar, even on wide screens/desktops.

Though I am -1 on using a "hamburger" menu to achieve this, from a UX (user experience) perspective, hamburger menus (and the icon) are widely used to collapse navbars on smaller screens, so many users/readers might get confused by seeing this used to achieve a different task.

I experienced this recently while doing some keyboard navigation assessment for JupyterBook - I and others were pretty confused as we had a mental model of what a "hamburger menu/icon" indicates in other apps and websites and the behaviour in JupyterBook did not match what we were expecting. This is not a violation of any rule or standard but can certainly be confusing and impact the user experience negatively.

In that sense, I would suggest an approach similar to what Docusaurus does by adding a << button instead (either at the top or the bottom of the sidebar)

https://user-images.githubusercontent.com/23552331/210871193-ac2d37b6-f567-46a1-92eb-d6f9a65465c4.mp4

[choldgraf]

+1 from me - if this is confusing in jupyter book I'd also welcome suggestions and PRs in the book theme for how to improve this! Hamburger menu is used right now because my UI/UX and CSS skills are not good enough to do more complex collapsing behavior. It'd be awesome if we could figure it out in this theme and we could just inherit in the book theme

As a note: the book theme actually used to use a <- arrow instead of a hamburger, but many people said they were confused by it because they thought it meant "go back", not "collapse", so we switched to the hamburger since this is a standard icon for "do stuff with other menus" - I agree it's not exactly the same though.

[trallard]

Interesting - I think something that might be adding to the confusion is that the hamburger button and the sidebar are next to each other (the button is floating to the right) rather than being more visually/structurally close. So it's not quite meeting the Gestalt proximity principle.

I can put together some ideas that we could use here and in Jupyter book.

[pllim]

I was just looking for this feature. I think a simple vertical think line with >> and << like how Python documentation does it would be sufficient for me.

xref https://github.com/astropy/astropy/pull/14867

[trallard]

@smeragoel - this might be an excellent first design task to look into as you familiarise yourself with this project.

[12rambau]

I was asking myself, isn't showing the icons we use in smaller screen sufficient ? . THe width of the sidebars are set by the css, javascript is only changing the display and sliding them in

[trallard]

Since the icon we show on small screens is a hamburger menu (see image below), this will introduce the issue I mentioned in this comment above - where other folks and I were pretty confused. We were expecting the hamburger icon to pull out a menu or something, but instead, it was collapsing the sidebar (or perhaps you referred to the one for the TOC?) I think it would still make sense to have a look from the UX POV to ensure this will be intuitive for the users.

[12rambau]

The vertical line proposed by @pllim will be an issue as many users have complained about the custom scrollbar being too thick (forcing us to remove it alltogether) so I'm not sure a 5-10px greybar will apeal to them more.

I checked the other existing theme (https://sphinx-themes.org/) and very few are offering this option:

• insipid is using the hamberger button same as jupyterbook
• furo is using the reverse indent as us for the secondary sidebar

hamburger menus (and the icon) are widely used to collapse navbars on smaller screens, so many users/readers might get confused by seeing this used to achieve a different task.

TBH I don't really see the problem, isn't it exactly what we are doing ? collapsing a menu with the sidebar content ? the arrows in general (double or simple) are to me even more confusing as they are widely used for pagination in technical documentations. When I typed "collapse sidebar website" in Google the first result from W3school is exactly using the hamburger icon for collapsing the sidebar. Shiny applications that I use on daily basis for work are also using it. I also checked framework and basic example from both bootstrap and vuetify are using the hamburger button for the sidebar collapsing.

And now that I finish writting this I think I get your point 😩 : People understand it's for collapsing they just think there is another sidebar waiting in the shadow

I checked the icon list and we cannot access in the free set to any sidebar icons but in https://github.com/pydata/pydata-sphinx-theme/pull/1250, we learned how to add extra icons so do you think it could be useful to use something like this instead: https://icon-sets.iconify.design/octicon/sidebar-collapse-24/ and flip it for "expand"/"collapse" ?

[drammock]

The vertical line proposed by @pllim will be an issue as many users have complained about the custom scrollbar being too thick (forcing us to remove it alltogether) so I'm not sure a 5-10px greybar will apeal to them more.

The docusaurus approach that @trallard proposed is subtly different: the vertical gray bar with >> in it is only there when collapsed; when the sidebar is open there is a horizontal gray bar at the bottom of the sidebar that contains <<. WDYT about that approach @12rambau?

Personally for consistency I'd prefer that the << and >> bars were in the same spot (like on Python doc site, like @pllim suggests), and one could argue that a little extra horizontal width is OK for something that has the function of reclaiming some horizontal space when you click it. It might also be possible to have that bar be very narrow, but grow in width on hover to make it an easier clicking target?

If that still seems like a non-starter, I'm OK with the docusaurus-style compromise of having the "collapse" bar be horizontal at the bottom of the sidebar, and the "expand" bar being vertical at the screen edge.

[trallard]

I am going to let @smeragoel look into a couple of options from a UX design POV and we can take it from there

[12rambau]

The docusaurus approach that @trallard proposed is subtly different: the vertical gray bar with >> in it is only there when collapsed; when the sidebar is open there is a horizontal gray bar at the bottom of the sidebar that contains <<. WDYT about that approach @12rambau?

If we go down this path, I would suggest to move the arrow at the top of the sidebars as the secondary sidebar border doesn't go to the bottom of the screen.

[smeragoel]

Okay, lots of excellent discussions here so I'll try to address all the points one by one!

1. I think we have a consensus on the fact that collapsible sidebars would be a good feature to have for non-mobile screens as well.

2. Now that we have decided that the sidebar will collapse, what approach do we use?

   a.Hamburger Icon: This seems like the most straightforward solution because it's what we use on mobile screens. But as mentioned by @trallard there are some issues with this approach. The hamburger icon is primarily used for expanding first. On mobile screens, the sidebar is hidden by default, and the existing design pattern is to tap on the hamburger icon for a menu to pop up. On desktop screens, we will have the sidebar expanded by default [1]. When the user sees an expanded menu with a hamburger icon, it will confuse them. The default behaviour is to expand, so users might expect another secret menu to pop up, but it will just collapse the sidebar. *chaos ensues* 😵‍💫

   [1] Why are sidebars expanded by default on desktop screens? Here's a good article that explains the cons of hiding content by default, especially on desktop screens.

   b. The docusaurus approach: This is definitely more intuitive when it comes to the function of the buttons. But, as noted by @drammock, the collapse and expand buttons change position and orientation, which is not great for the user experience. The fix here would be to maintain the same orientation and position for both buttons. Because we can't have a horizontal button when the sidebar is collapsed, that'd mean an approach similar to the Python documentation as mentioned by @pllim, but then we run into the issue mentioned by @12rambau in this comment. (Speaking of which, @12rambau could you provide some more context for this issue for me? It'd be interesting to understand the user problems with the custom scroll bar you mentioned).

   c. Using sidebar icon: As suggested by @12rambau, using a sidebar icon would be very direct. I created a potential mockup of the design with a floating button. I am not committed to the exact positioning of the button yet. I'm still trying to lock down what element to anchor the button to, but I'd love some input on this direction 😺

https://github.com/pydata/pydata-sphinx-theme/assets/98317216/ed8c86e1-69a3-458a-96fa-c51f9b66c107

[12rambau]

as per request, the custom scrollbar issue: https://github.com/pydata/pydata-sphinx-theme/issues/1239

[trallard]

Thanks @smeragoel I quite like the proposal of having the sidebar icon and keeping this in a consistent position.

[pllim]

I think I stumbled upon what was proposed in https://github.com/pydata/pydata-sphinx-theme/issues/1072#issuecomment-1595850036 but in real world over at https://mamba.readthedocs.io/en/latest/installation.html . Pretty much what was proposed but the location of the icon is slightly different. I prefer where they place it over at mamba docs, FWIW.

[12rambau]

and what if we keep the existing positioning (in the header navbar) with a tooltip + the brand new icon ?

[choldgraf]

I am +1 on trying option c above. I'd prefer the button to be in the article header but i also don't know how to combine it with the breadcrumbs in a non awkward way. So I think @smeragoel should give a shot at implementing the basic structure in that video and we can begin iterating from there.

@12rambau when you say "existing positioning" do you mean to have the collapse button to the left of the logo all the time? I feel like on wide screens there is value in having that logo flush to the left since it is such a common design practice

[drammock]

• I like the icon shown in the "option c" video
• I like the icon's hover effect but I'm not crazy about the rounded square frame being there all the time.
• I think the icon should be vertically center-aligned with the breadcrumb navigation
• I think it's horizontal position is basically fine (I agree with @pllim that the location of mamba's functionally equivalent hamburger icon is nicer, but I think @choldgraf is right that in our theme it competes for space with the breadcrumb navigation so doing it like mamba does is not really an option for us)
• Given how much the icon moves when the sidebar is collapsed, it seems like the main content barely grows in width at all. Is that adjustable / will it ultimately be user-configurable? (I lean toward us tweaking it here and now, but not exposing it as a user-settable parameter)

[smeragoel]

Thanks for the feedback everyone. I'll go ahead with this icon, mock up some different iterations of the positioning to see what works best, and also try to modify the button itself so that we don't have a rounded rectangle button just floating there all the time.

@drammock regarding how much the icon moves and how much the content grows, I think it's somewhat going to depend on the user screen-size. Obviously, we should anchor it to something (for example, the widest it goes is the header, so the sidebar icon never moves past the logo on top). You're right in pointing this out in the video, I don't think it's the best example. I'll make it more true to intention in the next mockups.

[drammock]

regarding how much the icon moves and how much the content grows, I think it's somewhat going to depend on the user screen-size

really? I think that the width of the left sidebar is fixed, and therefore the amount of space you could potentially gain for the main content is also fixed (i.e., unaffected by screen width --- as long as we're talking about widths above the cutoff for showing the left bar as a bar rather than in a drawer). But regardless of that, restating my earlier point: if I watch the little house icon in the breadcrumb (as a proxy for "left edge of main content"), I think it should end up further to the left when the sidebar is hidden. Currently it ends up aligned with the middle of the version switcher dropdown; I think it could go much farther.

we should anchor it to something (for example, the widest it goes is the header, so the sidebar icon never moves past the logo on top)

agreed that in "sidebar hidden" state the new icon should not move any farther left than the left edge of the logo in the topbar.

[smeragoel]

I made a new mockup with a different positioning and style of the button.

• In hindsight, moving buttons aren't good for UX, so this static positioning is better. The button is vertically center-aligned to the breadcrumbs, and left aligned with the logo on the header.
• I added a vertical line to denote a "sidebar area" of sorts when the sidebar is collapsed. This was done to minimize interaction between the breadcrumbs and the button. This line also exists in the expanded version currently.
• I also incorporated a more true-to-reality expansion of content. I wasn't sure what the behaviour of the "right sidebar" was going to be, so for now, I have kept it fixed but we can discuss whether that should also move with the main content.

I'll take a fresh look at this again tomorrow, to fine-tune the size and positioning of the button, but until then feedback is welcome 😸

https://github.com/pydata/pydata-sphinx-theme/assets/98317216/86e558ad-988e-4b2e-bd71-31215c1c6cca

[drammock]

that looks great IMO!

[trallard]

Thanks! This is much better.

really? I think that the width of the left sidebar is fixed, and therefore the amount of space you could potentially gain for the main content is also fixed (i.e., unaffected by screen width)

I am unsure if this is screen dependent - I would have imagined it would depend on the max width the main content container could take. I suppose we will have to figure this out during the implementation

[dprada]

I just opened a duplicate issue suggesting something similar to this feature. Let me at least give an explicit 👏🏻 to @smeragoel implementation. I was missing just that as a user of the theme.

I also dare to suggest that I would like the option to choose if the button is fixed -no matter the size of the screen- or not. I would leave it on -all the time- in the documentation of our library.

Big thanks for your work! This theme is fantastic!

[smeragoel]

I want to bump up this issue since we had some really good discussions and the design is done as well. I tweaked the last design to match the rest of the website and here's how it looks now:

https://github.com/pydata/pydata-sphinx-theme/assets/98317216/633fe316-d6d3-4d6f-9118-54612280626c

1. I have reduced the sidebar icon size to be more comparable to the home icon next to it.
2. I have also added explicit "Collapse Sidebar" text next to the icon for better accessibility.
3. In collapsed state, there is no space to add the "Expand Sidebar" text, but I have added it as a tooltip prompt.

I'm open to more feedback, but if there's nothing major, I think we can move forward with the implementation so that this feature is live!

[trallard]

Closing the loop here. I think this is a great design @smeragoel ✨ @gabalafou / @Carreau, I think we are ready to move forward with implementing this. I'm tagging you both in case any of you want to tackle this enhancement.