Show sidebar by default
SeanDS opened this issue · 15 comments
Great theme! I like it all, except one thing: the sidebar being collapsed by default. Can I configure insipid to display the sidebar by default? Apologies if this is in the documentation already but I didn't find it.
Thanks, I was waiting for this request!
I'm intentionally hiding the sidebar by default, see the first goal in https://insipid-sphinx-theme.readthedocs.io/en/0.2.9/intro.html#goals.
I didn't add an option (yet?), because I think it's better to hide it.
I think most themes do that wrong, and I think most of the time showing the sidebar is a waste of space and a distraction. Visitors should concentrate on the content, not on the sidebar. Don't even get me started on a second sidebar, which is just more distraction!
But I'm open for discussions, now that you brought it up!
I think (but have no data to back this up), that most of the time, visitors will come directly to the page they want to read (either via a search engine or via a curated link from somebody), and they don't actually need the sidebar in this case, it would just be a distraction.
Also, I have the feeling (but again, no data), that it's easier to discover that the sidebar can be shown than that it can be hidden.
What is the use case you have in mind?
Why do you think the sidebar should be shown by default?
On a more technical note, it's also easier and more consistent to hide it initially.
Because what would you expect on small screens (e.g. smartphones)?
If you come to a specific page you are interested in, do you want the sidebar to be open and blocking the content you are actually interested in?
I don't think so ... but then we have two different behaviors depending on screen size ... less consistency ...
I have actually thought about adding an option to show the sidebar by default, because then I could use that on https://sphinx-themes.org/#theme-insipid-sphinx-theme, where currently the sidebar is not visible on the screenshot. But in this case I think it would be good to have it. It wasn't important enough for me to do anything, though (also, it should only be visible on the left screenshot, not on the middle one).
Thanks for the detailed reply. I admire the vision you have for your theme and I hope it is compatible with my use case. In my case, despite your stated goal for the theme to be "boring", I really think a visible-by-default sidebar, at least for desktop screen sizes, is important as an option. Since you gave me the courtesy of a detailed reply, and stated that you're open to discussion, I will give some reasons:
- The docs I'm building are for a small academic software tool and the people reading it are almost all going to be doing so during their working day at a laptop/desktop. There's going to be plenty of screen real estate for a sidebar.
- My tool is frankly not important enough for users to spend time reading the prose of the main page to answer their question. The tool is (should be) obvious to use for most use cases, so those who seek out the docs will be doing so intentionally to solve a particular problem they're having. This is where having obvious sections easily discoverable via the sidebar saves them time, like a good readthedocs theme (e.g. borgbackup). This can of course be done badly, such as for hypothesis, but it's because the documentation author did a bad job, not because there is or isn't a sidebar. And while it's possible to put a big list of links on the main part of the page, that would not be visible from every other page like a sidebar would be, so users would have to keep going back to the main page to navigate to other sections, or figure out how to display the sidebar (and keep clicking the button to show it every time a new page is loaded).
- Maybe I'm weird, but on a personal level, I dislike any website or software tool that hides menus away. Firefox does it, Microsoft Word, WordPress, etc., and they all irritate me. The first thing I usually do is disable this hiding behaviour. Fortunately most tools remember your preference for next time using cookies, but this theme doesn't appear to do that (and probably shouldn't - a Sphinx theme storing cookies seems to be going a bit too far).
I hope my tone here comes across as constructive, which is what it's intended to be. The theme is really nice, it's clearly had a lot of work and attention to detail given to it, and it's provided for free, all of which I appreciate a lot. It's the best looking theme on sphinx-themes.org which is why I chose it, but the sidebar issue is putting me off. I hope you can consider adding an option!
I really think a visible-by-default sidebar, at least for desktop screen sizes, is important as an option.
Yeah, I'm open to that, we just have to come up with the details and see if it makes sense in practice.
I would like to try to implement a CSS-only solution for hiding the sidebar (based on the technique that the Furo theme uses on small screens), so it would also work when JavaScript is disabled.
I'm not sure yet how the default visibility can be controlled in this case.
When I'm doing this, I can also try to add an option for switching the default. I hope that'll be possible.
The docs I'm building are for a small academic software tool and the people reading it are almost all going to be doing so during their working day at a laptop/desktop. There's going to be plenty of screen real estate for a sidebar.
Yeah, sure, but if they want the sidebar they can switch it on, right?
And I also want to stress: just the fact that there is available space doesn't mean we have to put something there.
And I do like the sidebar, I use it all the time. But when I'm reading one page from top to bottom, I don't want to be distracted by it and I tend to switch it off.
My tool is frankly not important enough for users to spend time reading the prose of the main page to answer their question. The tool is (should be) obvious to use for most use cases, so those who seek out the docs will be doing so intentionally to solve a particular problem they're having. This is where having obvious sections easily discoverable via the sidebar saves them time, like a good readthedocs theme (e.g. borgbackup). This can of course be done badly, such as for hypothesis, but it's because the documentation author did a bad job, not because there is or isn't a sidebar.
Yeah, that sounds totally reasonable to me. I agree that the structure of the sections is important and that this is the responsibility of site authors.
One use case is quickly browsing through the docs to find some specific information (without using any kind of search!), another use case is reading through larger swaths of documentation.
In the former, the sidebar is very helpful, in the latter, the sidebar might be distracting.
Whatever the default setting is, one of them will be disadvantaged.
When using search (either the built-in one or a generic search engine), the sidebar is not necessary, right?
And while it's possible to put a big list of links on the main part of the page, that would not be visible from every other page like a sidebar would be, so users would have to keep going back to the main page to navigate to other sections, [...]
I don't want that readers have to rely on that.
They should use the sidebar for that.
But they have to somehow find out that the sidebar exists ...
or figure out how to display the sidebar
Yeah, that's the interesting part.
It seems to be unnecessarily hard, do you have ideas how to make it easier for them?
(and keep clicking the button to show it every time a new page is loaded).
That should not be necessary, the state is remembered between pages of the same (sub?)domain, except:
- if JavaScript is disabled
- if the pages are viewed locally (without being served by a web server)
- in this case I think the state is remembered between all pages in the same directory, but lost when navigating between directories, but this may vary between browsers
If you are testing the theme locally, you should use a web server (e.g. python3 -m http.server, or https://github.com/executablebooks/sphinx-autobuild).
Or is your documentation meant for offline consumption?
Maybe I'm weird, but on a personal level, I dislike any website or software tool that hides menus away.
Well that's certainly a matter of taste, and that's fine.
Firefox does it, Microsoft Word, WordPress, etc., and they all irritate me. The first thing I usually do is disable this hiding behaviour.
I guess this also applies to the topbar of the insipid theme?
I don't think I want to add an option that keeps it always visible.
For the sidebar, it should actually stay visible.
Fortunately most tools remember your preference for next time using cookies, but this theme doesn't appear to do that (and probably shouldn't - a Sphinx theme storing cookies seems to be going a bit too far).
Well it actually does.
It uses localStorage (https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) instead of cookies, but it stores the state in the user's browser.
Does this not work for you?
I hope my tone here comes across as constructive, which is what it's intended to be.
Yes, totally!
That all sounds good to me! To avoid quoting replies to quotes, I'll just give some standalone replies to the questions you asked to keep it brief:
- Just because there is space, it shouldn't be used: agree in principle, but we seem to agree it depends on the scenario, e.g. whether it's intended to be concise or verbose documentation, both legitimate.
- Sidebar not necessary with search: hmm, I also find Sphinx's simplistic search to be a bit useless too. I much prefer to first try to use the author's categorisation of their content (i.e. section headings, e.g. via sidebar!) to find what I need over the shotgun approach of text search. I'd actually say search shouldn't be necessary with a (good) sidebar, at least in the "concise" docs case mentioned above.
- Remembering of sidebar state: indeed, I noticed it remembered the state when I tried it on a web server. That seems like a totally legitimate use of local storage.
- Top bar disappearing: I have no qualms about that staying the way it is, because it's not really a frequently used part of the screen. An argument could be made for a visible-at-all-times link to the home page though, but I note it reappears if you move your cursor there. Why not add an option to show it all the time for those that want it though?
I think (but have no data to back this up), that most of the time, visitors will come directly to the page they want to read (either via a search engine or via a curated link from somebody), and they don't actually need the sidebar in this case, it would just be a distraction.
This is not true for me. Usually, I have bookmarks for the documentation of Python packages I need. I then go to their page and click on the function/class I would like to look at on the sidebar.
Just a silly observation from my side. When going to https://insipid-sphinx-theme.readthedocs.io/en/0.2.9/index.html the sidebar is shown for me per default (even after clearing the cache):
Seems to be that clicking "Ctrl + F5" is not sufficient. After clearing the page related cache, the sidebar is gone.
Alternatively, you could also open the "developer tools" of your browser and remove the sphinx-sidebar setting from "Storage" -> "Local Storage".
I think (but have no data to back this up), that most of the time, visitors will come directly to the page they want to read (either via a search engine or via a curated link from somebody), and they don't actually need the sidebar in this case, it would just be a distraction.
This is not true for me. Usually, I have bookmarks for the documentation of Python packages I need. I then go to their page and click on the function/class I would like to look at on the sidebar.
That's IMHO a reasonable use case.
But when you return to the page, it will anyway have the same setting as you left it.
I'm more interested in the initial visit.
If you visit a page that often that you put it into your bookmarks, I guess the initial setting doesn't really matter, right?
I think (but have no data to back this up), that most of the time, visitors will come directly to the page they want to read (either via a search engine or via a curated link from somebody), and they don't actually need the sidebar in this case, it would just be a distraction.
This is not true for me. Usually, I have bookmarks for the documentation of Python packages I need. I then go to their page and click on the function/class I would like to look at on the sidebar.
That's IMHO a reasonable use case. But when you return to the page, it will anyway have the same setting as you left it. I'm more interested in the initial visit.
If you visit a page that often that you put it into your bookmarks, I guess the initial setting doesn't really matter, right?
Yes, you are totally right. This is also the reason why I forgot that the toolbar is not shown the first time.
I played around with this a bit and I think I came up with a reasonable compromise:
Instead of having a boolean option (which doesn't really make sense anyway, since on small screens we want the sidebar to be hidden), we could provide a certain width that acts as a threshold: if the window is wider than this threshold, the sidebar is initially shown, if it is narrower, the sidebar is hidden.
I would choose a rather large threshold by default, so that it only kicks in when viewed in full screen on a non-mobile device, but I guess that would be fine for the situation described by @SeanDS.
The tentative name for this option would be initial_sidebar_visibility_threshold, which a default value of 100rem (for comparison, body_max_width is 45rem by default).
Users of the theme would of course be free to choose a smaller (or larger) threshold.
Of course, all of this is only relevant until the visitor toggles the sidebar, from then on the user's choice will be kept (as it is done already).
What do you think?
OK, I've implemented the mentioned things in #70.
Here's a preview: https://insipid-sphinx-theme--70.org.readthedocs.build/en/70/
What do you think?
Is that enough to solve this issue?
It's quite a big change, so please feel free to test it thoroughly!
Thanks for this. It looks good for me as a desktop user, though as I make my browser window smaller the sidebar never goes away. Is this intentional?
Yes. Changing the window size does not change the sidebar visibility.
That's one of the reasons for the initial_ in initial_sidebar_visibility_threshold, because it only depends on the initial window size. The other reason is that it is only relevant on the initial visit (unless the sidebar hasn't been toggled and the visibility has therefore not been stored).
However, if you make your window smaller and visit the page again (hitting "reload" might not be enough), the sidebar should be hidden (assuming the state has not yet been stored).
Aha, I see. Yes, looks good then!