Made sidebar in docs nicer while also adding link to examples.

[Martinsos]

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 .

[Martinsos]

@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? I can understand/see that.

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 believe this also sounds like a valid concern, and very likely others are experiencing this also. Do you think this point has some weight?

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?

[Martinsos]

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, sorry.

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

[infomiho]

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

[Martinsos]

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 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:

1. Me being who I am shouldn't completely devalue my opinion and ability to put myself in other's shoes.
2. We can't really say if that sidebar is the worst or the best piece of their docs, even if many people are working on that.

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. They have stuff on top level, but it almost fits on the screen, and each of those things opens to a bunch of stuff in it. So it does go quite more in depth than into surface. And, they are even able to fit API reference on the screen in the sidebar. So I would say closer to this PR than current state.

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: https://remix.run/docs/en/main .

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.

[Martinsos]

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: https://github.com/wasp-lang/wasp/issues/2071 .

[Martinsos]

Ok, so I reverted the PR to how it was before, all expanded. I also reverted the change I did where non-top-level categories were colored, now they are not colored any more.

So now sidebar looks like in the following image.

[sodic]

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.

[Martinsos]

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

[Martinsos]

Did a little poll on Discord here, as an additional data point we might want to consider: https://discord.com/channels/686873244791210014/1080864617347162122/1245474468810199212

[sodic]

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.

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

[Martinsos]

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.

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: