kubeflow
Improve sidebar style for deeply nested pages
The current sidebar is almost unusable for the deeply nested pages (like those in KFP). The sidebar gets all bunched up and it's hard to know which pages are in what folders.
This PR significantly improves the readability of the sidebar links by doing the following:
- Expands the sidebar width
- Remove unnecessary padding and indents
- Putting a vertical line to show where each folder starts and ends
- Bolding the "chain" of pages which leads to the currently active page
This PR also does the following:
- applies a max-width to the site, to prevent very wide screens making the site hard to read
- fixes the top navigation bar for smaller screens, the issue was the long "event promo" links were ending up underneath the logo
- adds a subtle rotation on the "expand section" arrow when you are hovering
- removes an invalid
OWNERS.mdfile (note the.md), which was showing up as a nameless page.
Laptop Screenshots
OLD
NEW
Widescreen Desktop Screenshots
OLD
NEW
Mobile
OLD / NEW
@james-jwu @jbottum @andreyvelich @terrytangyuan can one of you please review or approve this website PR?
It's a very important readability change, and makes no changes to the content so it should not be controversial.
The best way to see how much better it is, is to explore the preview site for yourself:
- https://deploy-preview-3816--competent-brattain-de2d6d.netlify.app/docs/components/pipelines/user-guides/data-handling/parameters/
@thesuperzapper, thank you so much for that. The expanded sidebar, combined with the 'chain of lines, ' improved readability greatly.
I think you should change the animation on the 'expand section' arrow. Sometimes, the rotation got stuck at a 30' angle on hover:
I prefer this arrow pointing east when collapsed and pointing south when expanded.
Thank you for this. Additionally, we should discuss how we can decrease the left panel since this change will reduce the actual size of the document (cc @StefanoFioravanzo )
@thesuperzapper Thanks for this, it's a great UX improvement.
I back @ederign's proposal - can we remove the ~30 degree on-hover animation? I get why you put it, it can be a nice visual touch, but I feel like it overstimulates in this case.
@andreyvelich On the sidebar width, we do have an issue with a content tree that's too deep. When the sidebar is too narrow, you end up with folding titles. In the current preview the sidebar does seem too wide though. @thesuperzapper would you consider finding a balance between the current width and the one you propose? Maybe something in the middle would work?
Overall awesome change, thanks
Locally, the left panel sidebar issue only happens on large screens.
If we change the left sidebar to col-xl-2 (instead of col-xl-3) and the main to col-xl-8 (from col-xl-7), it will look like this:
But it will fold the titles on large screens. In the end, it is a matter of taste; both work for me.
Also, for some reason (I don't have the context), the main content was set to max-width:80%, which makes the main use only a partial size of the screen. I've changed to max-width:100% locally on the screenshot, but I don't know if this breaks anything.
@ederign @andreyvelich @StefanoFioravanzo thanks for everyone's feedback.
I have made the following changes:
- removed the rotation on the hovering of the arrows
- made the sidebar slightly smaller
- fixed the issue raised by @ederign about content only being able to use 80% of the main section
- applied a max-width to make the site much more readable on very wide screens:
- This was a nightmare to get working cleanly across the entire site, but I think it has significantly improved readability for wide screens, try it for yourself and see.
Please take another look on the preview site but I think this PR should be ready to merge now.
After this change I can see that content is centralized on the big screens and only occupies 50%:
Suggestion that may be out of scope for this PR: How about we auto-collapse the current open top-level menu when you open a new one? So we avoid an excessively long sidebar tree
This may work well also when browsing the components sections. Closing the tree of the currently open component when browsing another one
1 and 2 are fixed!
For 3 and 4, I found an issue:
@ederign that issue was actually present in the existing page, it was caused by someone including the entirety of bootstrap CSS in a
I have manually removed that bootstrap code and it mostly fixed the style issues on that specific page (it's not perfect, but it's still better than before).
Suggestion that may be out of scope for this PR: How about we auto-collapse the current open top-level menu when you open a new one? So we avoid an excessively long sidebar tree
This may work well also when browsing the components sections. Closing the tree of the currently open component when browsing another one
@StefanoFioravanzo this is already the behavior, when you click on a page, only the "chain" leading to your current page remains open.
It would be very unexpected for us to close pages while people were "browsing" for a page (before clicking).
Either way, lets discuss that in a seperate PR so we can merge this one.
After this change I can see that content is centralized on the big screens and only occupies 50%
@andreyvelich is this a positive or negative comment?
The width-limit increases the readability by preventing very wide screens from having content on the far edges of the screen.
If there are no more comments, and people are ok with the width-limit, I think we can merge this.
I did one last small cleanup to the styling in https://github.com/kubeflow/website/pull/3816/commits/1f89a55465360a1d5479162a49a471a13ca8d7c9.
The main fixes were:
- Homepage is now properly centered
- On small screens, there was a slight stripe of the darker border color, which should have only been visible on larger screens (with sidebars)
- Added a small border outline at the top of the page on mobile (below the search box).
I think this should be ready to merge now.
@thesuperzapper
This is already the behavior, when you click on a page, only the "chain" leading to your current page remains open.
That's not true. See my screenshot above. If what you said was true, how could I have found myself with that content tree?
After this change I can see that content is centralized on the big screens and only occupies 50%
@andreyvelich is this a positive or negative comment?
The width-limit increases the readability by preventing very wide screens from having content on the far edges of the screen.
If there are no more comments, and people are ok with the width-limit, I think we can merge this.
From my point of view this makes our docs harder to read since the documentation area is very small. Can we just follow the same settings as Kubernetes docs since they also use Hugo ? https://kubernetes.io/docs/concepts/overview/components/
I prefer their settings.
@thesuperzapper
This is already the behavior, when you click on a page, only the "chain" leading to your current page remains open.
That's not true. See my screenshot above. If what you said was true, how could I have found myself with that content tree?
@StefanoFioravanzo once you click on any page everything but the current page will close. Note, I am not talking about clicking the arrow, I am talking about clicking the page.
Similarly when you refresh the page all other open sections are closed.
Either way, feel free to raise a separate PR if you want different behavior.
After this change I can see that content is centralized on the big screens and only occupies 50%
@andreyvelich is this a positive or negative comment?
The width-limit increases the readability by preventing very wide screens from having content on the far edges of the screen.
If there are no more comments, and people are ok with the width-limit, I think we can merge this.
From my point of view this makes our docs harder to read since the documentation area is very small. Can we just follow the same settings as Kubernetes docs since they also use Hugo ? https://kubernetes.io/docs/concepts/overview/components/
I prefer their settings.
@andreyvelich having a max-width makes reading the page easier. Without it, the page is hard to read on a very wide screen.
It's well established that people find it easier to read things with margins and shorter line lengths. Give it a try yourself, show people the two pages and ask which they prefer.
If you are concerned about the specific max-width I have used, this is easy to change with a single variable. However, in my testing (and when compared to other websites), a max-width of 1440px/100rem was typical and easiest to read.
For reference, other docs websites already do this this like ArgoCD/Workflows, Istio and more.
PS: what's also interesting is that even with the width-limit, the height of the page remains the same in most cases.
PSS: let's do some user testing, or just ask a few other community members. But remember, this change affects only a small fraction of users, as almost no one reads these pages on a wide/4k screen.
Here is a good comparison for a 4k (2560x1440) screen. Remember in the real world, the left and right sides would likely be at least 27 inches apart on a screen like this. Also, if someone wants, they can simply zoom the page.
It's well established that people find it easier to read things with margins and shorter line lengths. Give it a try yourself, show people the two pages and ask which they prefer.
I mean this is very subjective, we can't say it for all of the users.
Looking at other Kubernetes project, they all have wider section for doc content:
- Kubernetes: https://kubernetes.io/docs/tutorials/hello-minikube/
- Kueue: https://kueue.sigs.k8s.io/docs/concepts/admission_check/
- Istio: https://istio.io/latest/docs/overview/what-is-istio/
My feeling is that we should just make the same settings as Kubernetes Hugo website, given that their website has the largest user attention.
It's well established that people find it easier to read things with margins and shorter line lengths. Give it a try yourself, show people the two pages and ask which they prefer.
I mean this is very subjective, we can't say it for all of the users.
Looking at other Kubernetes project, they all have wider section for doc content:
- Kubernetes: https://kubernetes.io/docs/tutorials/hello-minikube/
- Kueue: https://kueue.sigs.k8s.io/docs/concepts/admission_check/
- Istio: https://istio.io/latest/docs/overview/what-is-istio/
My feeling is that we should just make the same settings as Kubernetes Hugo website, given that their website has the largest user attention.
@andreyvelich the Istio site you linked uses a max-width of 1440px (like what I am proposing in this PR), and I think it's much easier to read than the Kubernetes website.
If we are talking about the Kubernetes website specifically, it's likely not because they don't want a width-limit, but because the default theme does not have it, and it was quite complex to implement.
Here is a screenshot of the Istio website:
@andreyvelich as long as we agree a fixed-width makes sense, we can discuss making the sidebar smaller.
But I still think it's worth keeping the wider sidebar because we have much more deeply nested pages than istio.
Perhaps @ederign can share some of his design experience and weigh in on what he thinks is best?
BTW, I am going to be on vacation till next Monday 30th July, so if you need any follow up commits to this (or other) PRs, it will need to wait till then.
This PR should be ready to merge (if we all can agree on the sidebar width), so feel free to do that if you want these fixes in.
@ederign could make a follow up PR if needed, because I think the changes are worth having soon, with the influx of 1.9 users.
I agree with @thesuperzapper that having a fixed max-width makes reading the page easier and more accessible. A max width of 1440px/100rem sounds to me like a good starting point for large screens, especially when balanced with the depth of our submenus.
If people are interested in reading more about this:
Having the right amount of characters on each line is key to the readability of your text. ... Too wide: if a line of text is too long the reader’s eyes will have a hard time focusing on the text. This is because the line length makes it difficult to gauge where the line starts and ends. Furthermore it can be difficult to continue onto the correct line in large blocks of text. [link]
If a font size is too small and the line length too long, readers will have to strain to read the text, which causes their eyes to fatigue [link]
We can always discuss the size of our main panel, but I think a maximum width is important for readability.
From my point of view, we should at least follow the Istio settings. Right now the area for docs looks very small.
@andreyvelich in the interest of getting this PR merged, I have reverted the sidebar to be the same size as the current website.
I think we are good to merge if @andreyvelich and @ederign give it a look over.
Also, in the last commit I made the following changes:
- Fixed a bug where the homepage header would disappear on large mobile screens
- Implemented a proper swagger-ui page for the pipelines API:
- Made the "feedback on this page" links pre-populate the issue with which page the user was on
This PR includes important changes that improve the web page, and I would like to see it merged as soon as possible. I'm fine with having the 'Try out' issue fixed in another PR (I can even send the PR myself later).
@ederign rather than disabling the "try it out" feature, I have made a system to allow users to put their own URL in.
It will still not work unless they have the appropriate authentication setup, but it makes it much easier to use the UI to formulate a request to run locally.
I have also added a preamble that explains a bit more about the API and how to use it on the Swagger pages.
Please review again and LGTM if you are happy now.
@thesuperzapper is this header expected? (at link)
@ederign I have changed the way the Swagger JSON is embedded so I can remove the hard-coded introduction/google-email, take a look:
@ederign I have made some final tweaks based on feedback from people I showed:
- made it so the logo is always the leftmost thing on the page (looks better)
- fixed the sidebar color bleeding into the page on mobile screens (where there are no sidebars)
- improved the padding of the table-of-contents on mobile (it was squished up on the left side of the screen)
People seem to be happy with it now, so if you can do a final review, then we can merge this. For reference, here is a page: OLD, NEW