Documentation site improvements

[aight8]

Mark active submenu automatically

Regarding: all pages
Go for example to this page: https://webpack.js.org/api/plugins/compiler/

Compiler <- active

• Watching
• MultiCompiler
• Event Hooks
• Examples

It's confusing because the sub menus can never be active, they are anchors. This could assume a reader it's a separate page. In my opinion the subpages must 1) be a separate page 2) or mark the current submenu as active while scrolling or clicking on the anchor.

Currently

Would be better

Near that:

• If you just open a main menu it, it will mark the main menu item as blue. So now your current active main menu item is blue and the main menu item which you opened. In other words: It marks just opened menu items instead of only the current active one.

Prevent content scrolling if scroll in menu (usability)

The content start scrolling if you overscroll the menu scroll area. This should be prevented since if someone start scrolling the menu he want scroll in the menu and never the content. This ends up that the current content position is scroll to much down or up the menu.

Cluttered plugin related pages

WIP
https://webpack.js.org/plugins/

Documentation -> CLI Menu entry

Click Documentation -> CLI

CLI never could be active. It redirects to Documentation -> API -> Command Line Interface (CLI)

I think redirecting is more confuses then helps - beside that the CLI menu point never can get active. One concept of navigation would be better.

Sticky navigation

There are currently 3 menus. 1) Header, 2) Sub-header (only for documentation), 3) Sidebar-Menu (with an toggle anchor submenu)

The Sidebar-Menu is sticky, and you see most time all menus (if it not overflows), but you lost the menus from the header and sub header. It's irritating if you start search something and the header menus disappears every time but a part of the menu is sticking.

Menu item overflows

Reading: Some menu items with overflow submenu items
Go for example to this page: https://webpack.js.org/api/loaders/

Maybe it were a great idea to present the submenu items a separate scroll area. So the sidebar menu never overflows and you can see always all top menu items. The sub menu items just fill the rest of the space.

So you don't lose navigation and have a perfect overview where you are.

Scrolling Who knows where I am here? Somewhere in the middle of the docs. Lost navigation.

Menu side bar "Version x.x"

You can't change to another version of the documentation and it's not really a part of the menu (you can't click it, it's kind of a menu "title"). I'm not sure if it's necessary there.

Change menu reloads the page

Yes this is more work, but I recognized if I click to another page the whole menu is reloading as well. The biggest problem: The scroll position of the menu is not maintained. It kicks me out of orientation - lot time you just click somewhere to see it is the right page but you must reorientate where you was in the menu.

Other ideas

• use icons maybe somewhere

[skipjack]

@aight8 you make some good points here. I'm currently working on implementing the design shown in #438, I'll try to take some of these into account I go as well.

[skipjack]

Ok, some thoughts as you've listed a lot here...

Mark active submenu automatically

Displaying the initially active submenu option would be easy but maintaining it on scroll would a bit more to maintain. If someone wants to take a stab at this and/or has a library or open source component that would help with this, I'd be happy to review a PR. However I think it's also probably ok to just keep it simple for now.

Prevent content scrolling if scroll in menu (usability)

Not sure if this is really that much of an issue, there are a bunch of other sites (e.g. sketch docs that work this way and at least in my experience, the behavior is pretty easy to get used to. If we did a gitbook-like layout with a fixed width/height this wouldn't be an issue but would definitely be a big change.

Cluttered plugin related pages

Note sure what you mean... can you elaborate?

Documentation -> CLI Menu entry

This is definitely an issue. I'm working on cleaning up and synchronizing the routing/content structure as we speak (see antwarjs/antwar#124 and my comment here). After looking into it a little more I think it probably just makes sense to get rid of this link.

Sticky navigation ... It's irritating if you start search something and the header menus disappears every time but a part of the menu is sticking.

Yea that's fair... we talked about adding react-headroom for this a while ago but were blocked by an incompatibility with preact. However, I believe it's now compatible so feel free to PR. Keep in mind that with the fixed sidebar position will need to be adjusted when the header is fixed.

Menu item overflows ... Maybe it were a great idea to present the submenu items a separate scroll area. So the sidebar menu never overflows and you can see always all top menu items.

I agree the long menu is a problem. Idk about the proposed solution though, a triple scroll behavior (submenu > sidebar > page) could feel pretty messy. I think this is more an issue with these pages being too long a probably need breaking up. If we allow grouping pages (#438), pages like "Loader API" could instead be a group with a few child pages with much shorter anchor link sections.

I also think this at least somewhat improved with the updated design where the delineation between anchor and page links is much more clear.

Menu side bar "Version x.x"

I agree it would be great if it was a dropdown but that's probably a ways off. I changed this to a badge which I think is an improvement and we do need to include the current version that's being documented somewhere, did you have somewhere else in mind?

Change menu reloads the page

Yea I see what you mean, but there would be a lot more work involved in this. I know some other react-based static site generators like phenomic and gatsby support this but I'm not sure if antwar supports this. @bebraw are you planning to add this to antwar or are we still looking to port this project to another generator?

Other ideas ... use icons maybe somewhere

Could you elaborate? Where exactly?

As it stands right now, this issue contains a lot of points. I'll leave it open for now so we can collect some more thoughts but it probably makes sense to break the some of these out into their own issues/PRs. @aight8 let us know your thoughts/answers, @webpack/documentation-team interested in other thoughts/opinions on these things as well.

[bebraw]

Yea I see what you mean, but there would be a lot more work involved in this. I know some other react-based static site generators like phenomic and gatsby support this but I'm not sure if antwar supports this. @bebraw are you planning to add this to antwar or are we still looking to port this project to another generator?

The right way to do it would be to implement a little router on top of the site. The problem is that I'm extremely strapped for time at the moment (~7 hours per week) and there are higher priority issues to look into.

We haven't heard back from phenomic and the third guy that wanted to port the site. But if someone wants to take over the site development, I won't stand in the way.

[skipjack]

Closing for inactivity and scope...

However, some of the points here were addressed in #1046 and a few more will be in #1153. As to your other points, some of them are "won't fix" (like sidebar version) and some require either a significant port which we likely won't be tackling immediately. I may tackle porting this site to phenomic, which would address some of the things you mentioned (like making it a "universal" site, no full reload), however for the time being our main focus is to knock out the remaining content and clean up the existing content.

We can discuss more here, but let's create more targeted issues/prs for the things that we agree should be resolved. @aight8 if you could give me answers to those questions I asked above, that would be help me to understand, and potentially fix, each issue better.