Closed xDivisionByZerox closed 2 weeks ago
ST-DDT
commented
2 weeks ago I don't understand your main menu suggestion.
As for the sidebar suggestion 1, I like it, I would like to try the actual look and feel though. Does vitepress support that natively?
xDivisionByZerox
commented
2 weeks ago I don't understand your main menu suggestion.
Does this make it more clear?
| Before | After |
|---|---|
As for the sidebar suggestion 1, I like it, I would like to try the actual look and feel though. Does vitepress support that natively?
Yes. The screenshots in the issue where done by changing the vitepress config locally. Should I provide a PR with only the sidebar change?
matthewmayer
commented
2 weeks ago I'm neutral on the main menu changes Solution 1 for sidebar seems like a definite improvement so I'd do that.
Also I feel the "API Reference" should show the sidebar. Currently it is hidden there.
ST-DDT
commented
2 weeks ago Should I provide a PR with only the sidebar change?
Yes please. When writing code, I can imagIne the feeling just from text. But for stuff like websites, I like demos/PRs for these because they allow me to experience the change.
If the main menu change isnt conflicting with the other change, you can create a PR for that as well. Thanks for the clarification.
Description
As a user of Faker, I regularly use the website to look up documentation related to Faker. One thing that always confuses me is the way the navigation (main menu and sidebar) works. With the expectation of "Try it" and the Version links all other items navigate to a page that looks the same layout-wise. You have the actual content in the center, an "on this page" menu to the right, and the seemingly same docs menu (further referred to as sidebar) to the left. I said "seemingly" since only the items of the subsection you are currently in are fully listed (except for "About").
One inconsistency that I noticed is that the API section contains an item "API Reference" if the current navigation is not in "/api/". This item does not appear if you are in this subsection, tho. Another thing that was weird to me is that the "Guide" section only contains the item "Usage Guide" if not currently under "/guide/". But if I click this item I get instead redirected to "Getting Started", not "Usage" as I would have expected from the previous item name. Additionally, this makes it hard for me to navigate between main sections as I might have to click the "placeholder item" first to load the entire subitem list in the sidebar.
Suggestion
Main Menu
Please keep in mind: In the future, two new main sections "Contributing" and "Maintaining" will be added to the docs.
Solution 1 - Group Related Items
The main menu items "Guide", "API" and all items under "About" navigate to pages that feel the same through their shared sidebar items. They should be grouped under a new main menu item "Docs".
Solution 2 - Keep As Is
Keep the main menu as it is. In this case, the sidebars should propably be readjust. Currently you can click on the "API Reference" item in the sidebar to get to the API page or you press the API navigation item in the main menu. This might lead to confusion whether both ways lead to the same page. If a link already exists in the main menu, it's submenu should not be present in the sidebar for different pages.
Sidebar
Solution 1 - Collapsible Main Sections (favored)
Always show all list entries for all main sections in the sidebar, but make them collapsed by default. Only the main section we are currently in should be expanded.
Solution 2 - Main Section as Link
Do not show any list entries for main sections in the sidebar, but make the main section heading a link itself. This does not get rid of the problem that I have to click through multiple pages, but at least does not five me wrong expectations.