Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Website] Change Navigation Behaviour #2852

Closed
xDivisionByZerox opened this issue Apr 27, 2024 · 4 comments · Fixed by #2855
Closed

[Website] Change Navigation Behaviour #2852

xDivisionByZerox opened this issue Apr 27, 2024 · 4 comments · Fixed by #2855
Labels
c: docs Improvements or additions to documentation p: 1-normal Nothing urgent
Milestone

Comments

@xDivisionByZerox
Copy link
Member

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

In "Guide" In "API" In Any "About"
image image image

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.

In "Guide" In "API" In Any "About"
image image image

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.

@xDivisionByZerox xDivisionByZerox added c: docs Improvements or additions to documentation p: 1-normal Nothing urgent labels Apr 27, 2024
@ST-DDT
Copy link
Member

ST-DDT commented Apr 27, 2024

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
Copy link
Member Author

I don't understand your main menu suggestion.

Does this make it more clear?

Before After
image image

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?

@xDivisionByZerox xDivisionByZerox added this to the vAnytime milestone Apr 27, 2024
@matthewmayer
Copy link
Contributor

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
Copy link
Member

ST-DDT commented Apr 28, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
c: docs Improvements or additions to documentation p: 1-normal Nothing urgent
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants