Made sidebar in docs nicer while also adding link to examples. #2068
Conversation
web/src/css/custom.css
Outdated
| color: var(--sidebar-category-color); | ||
| font-weight: bold; | ||
| font-size: var(--ifm-h6-font-size); | ||
| .theme-doc-sidebar-item-category > .menu__list-item-collapsible > .menu__link { |
There was a problem hiding this comment.
| .theme-doc-sidebar-item-category > .menu__list-item-collapsible > .menu__link { | |
| .theme-doc-sidebar-item-category-level-1 > .menu__list-item-collapsible > .menu__link { |
Might I suggest this change, it feels cleaner since only the top level is yellow.
 |
 |
|---|---|
| Before | After |
There was a problem hiding this comment.
But I did it on purpose, to make it clear what is "openable". Otherwise, once you open those Operations, it is a "see" of white/black, it is hard to see who is parent a bit. Notice only top level is bold though.
There was a problem hiding this comment.
But the caret symbol is the visual indicator of what can be opened. That's how it looks in the default Docosaurus theme and I think it's good enough: https://docusaurus.io/docs/2.x
Doing too much design will lead to poor design since we are not designers, that's why I'd like to stick to the default as much as possible.
There was a problem hiding this comment.
Ok, done! I don't want us to shy that much from design though, we can try, but your are right if docusaurus has it that way, probably be should also.
web/sidebars.js
Outdated
| @@ -14,8 +14,8 @@ module.exports = { | |||
| { | |||
| type: 'category', | |||
| label: 'Tutorial', | |||
| collapsed: false, | |||
| collapsible: false, | |||
| collapsed: true, | |||
There was a problem hiding this comment.
We kinda lost the overview of all the topics with everything being collapsed. We had this in the old docs if I'm not mistaken and we decided to keep them expanded in this latest iteration.
For example, data model is not indicative of operations or advanced is not indicative of jobs. You have seen jobs and now you want to know more, but you have to expand multiple sections to find them.
There was a problem hiding this comment.
Yeah, but there was so much stuff you really couldn't see anything. So instead of having a top level overview, you had a glimpse into 20% of the docs and that is it.
This way you can scan and find your way around.
If we have important stuff we want to take up, we can do that by organizing a new category. For example, take Operations to the top level. Or, we can put data model and ops and more stuff under "Foundations", and then the rest under "Advanced".
So I am not saying we can't improve this, but I think the old solution stopped working at some point when the docs grew, and this is the "future".
There was a problem hiding this comment.
Yeah, but there was so much stuff you really couldn't see anything. So instead of having a top level overview, you had a glimpse into 20% of the docs and that is it.
It was more like 50%, but that's fine since users know how to scroll. It's much easier to scroll than to open 5 sub menus, not to mention the feelings you get while looking for something you can't find or even worse not knowing where to start.
I'll let @sodic comment of this as well, but we kinda took this from Vue.js docs: https://vuejs.org/guide/introduction.html since they were the gold standard in our eyes.
There was a problem hiding this comment.
We could in theory go somewhere in between: have some categories collapsed by default (like Tutorial and Auth, those don't benefit from being open), and some open by default (e.g. Advanced).
Although it seems to me like some kind of reorganization would be the best solution.
There was a problem hiding this comment.
@infomiho for me it was a huge mess on the left, very hard to get any kind of an overview, or what is important or what is not. I keeping having that issue very time I look at the docs. This finally enables me to navigate the top level and dive to the depth I need.
There was a problem hiding this comment.
I dropped this part our of this PR to be discussed separately!
There was a problem hiding this comment.
I have to say I'm not a fan of the change, sorry 😅
I strongly prefer what we had before. So, if it's a vote, I vote against it.
I understand the motivation but I don't think this is not the right approach.
Instead, we should choose what to feature in the sidebar instead of featuring everything and collapsing it. We could collapse the unimportant stuff on the bottom.
Perhaps even putting the important stuff first is enough (without collapsing anything).
If we do go through it, then I suggest:
- Dropping the yellow text, it looks weird.
Definitely dropping the red rectangle.Miho told me he added this to emphasize, my bad.
|
@infomiho @sodic from what I get, you like the old layout because it allowed you to scroll through stuff and get a feel for all stuff that is part of the docs, right? For me, what wasn't good is that I had hard time navigating through that noise, it is too much at the same time, and instead of at one glimpse seeing what docs offer and then diving deeper into what I need, I have to scroll through a bunch of information that additionally all in the same color to make it harder to distinguish. I would say both are valid requirements. Why don't we do something in the middle? People certainly don't need to see all the sections of tutorial on first glance, just Tutorial is enough. Same goes for Auth. While Advanced we can leave open, so they can see all the features. So what I am suggesting is we collapse the category that create more noise than bring information, and leave open those that do the opposite. How does that sound? |
No need to apologize, why would I be offended by you not agreeing? I do think my point is valid, but the point is to figure out together the best thing, so whatever we figure out I will be happy with. Ideally, we would find something that satisfies all the problems we identified. I commented above on such possible solution. lol red rectangle |
I see that side of the argument and of course it will be a trade off between visibility and cleanliness. I'd like to point out that the way you navigate or perceive docs as the framework author is different than a beginner or intermediate users. That's why I'm reiterating the inspiration for the current layout: Vue.js docs which have a bunch of docs maintainers and iterated on them a lot. |
That's a fair point and has weight, but:
That said, what others are doing is a good enough way to resolve this situation where we don't have a better way to resolve it, I agree with that, I just don't want us to accept blindly that what others are doing must be the best way to do it. Btw I just took a look at Vue docs and I see that they first have, as a dropdown, option to choose between Guide, TUtorial, Examples, and couple more things. Then, once you go into Guide, you get this expanded list on the left that is very simple. So they in a sense do have a step first where you get an ability to choose from high level. Although it is quite different also. And that sidebar in Guide doesn't look like much thought was put into it -> maybe it is and this minimalism is the perfection, but maybe there just wasn't. Let's take a look at React: https://react.dev/learn and https://react.dev/reference/react . I would say their approach is closer to the change I proposed here? The whole Sidebar fits on the screen, and you can expand it as needed. There are some differences, but I would say it is obvious they are more on the side of high level overview that you expand, than everything listed out for you and you nee dot scroll through it. Svelte: It is all expanded, but again, it fits on screen. Smaller font also, easier to have an overview. Ok let's take a look at something with bigger API surface, like Wasp: Next. Laravel: high level overview, all collapsed, like this PR: https://laravel.com/docs/11.x/readme . Remix: high level overview, all collapsed, like this PR: Tailwind: all expanded, doesn't fit at all into screen, so closest to Vue and us at the moment, before this PR: https://tailwindcss.com/docs/installation . Looks quite split: some do one approach, some other, and some are somewhere in between. It doesn't give me grounds to say that what I did in this PR is the best approach for sure, but I think it does give ground to say that there is no reason why what Vue is doing is the best approach. |
|
I tried to do a couple of things at the same time here, and since some of them I believe are easy to agree on and others seem to not be so easy to agree on, I will reduce this PR to cover only the easier stuff, and I created this issue to capture the harder stuff: #2071 . |
|
Ok, so I reverted the PR to how it was before, all expanded. So now sidebar looks like in the following image.
|
|
As mentioned, I don't think section titles should be yellow. It feels like we shouldn't use our highlight color for something that isn't highlighted/selected. If you ask me, only the currently selected page should be yellow (as is the case now). I'm also not a fan of collapsable sections (as explained above). I'd rather keep it flat. All in all, I still don't see these changes as a clear improvement and prefer the older look. If it were up to me, I'd just add the Examples link and leave the design changes for another time. That said, if you guys want to change it and have done some research (I'm just looking at it and saying what I think), I won't object. |
|
@sodic I can reverse the yellow color, although I liked it, but I get the argument. Let's see what somebody else says. I think yellow throws in some nice demarkation here between the sections. Some of the design changes (spacing and some small fixes) I will have to keep because adding Examples wasn't working otherwise (we never had such top level link so design for it was broken). Collapsable stuff -> now it is all flat and open, so that is as before, then only thing is you can collapse them manually if you wish, I don't see how is that an issue. Just to be clear, this is what it looks like right now:
Here goes grey version for comparison:
|
|
Did a little poll on Discord here, as an additional data point we might want to consider: https://discord.com/channels/686873244791210014/1080864617347162122/1245474468810199212 |
Oh, ok then, didn't know that. I thought it was collapsed. In that case, everything's fine with me. I prefer grey to yellow (for reasons already listed), but both are fine. Please just test it on a light background if you haven't (and include the screenshot). |
Tested it already, it looks good! Here is screenshot:
|
Main thing I wanted to do was add Examples link to the top level.
But to do that, I have to update the styling to be more uniform as it didn't account for having non-category stuff at top level.
This is what it looked like before this PR:
This is what it looks like now with this PR (notice also additional Examples link in the sidebar at the top level):
Closes #2009 .