Few aesthetic things about the web site

geeknoid commented 7 years ago

We should support specifying whether a section entry should default to expanded or collapsed in the left nav.
The color scheme for the tooltip for the Edit this Page button doesn't match the rest of the site very well.
The magnifying glass next to the search box probably should highlight orange upon hovering. It could probably also use a tooltip.
The Copy button on PRE sections is rendered inconsistenty. For example, on this page https://istio.io/docs/tasks/integrating-services-into-istio.html it is not as tall as on other pages.
We should consider adopting the left-nav tab design from amalgam8.io. The left nav can be displayed or hidden, making more room available for the document content.
We should consider implementing the TOC as a pull down menu at the top of the page. This would look visually cleaner overall.

geeknoid commented 7 years ago

I put all the things into a single issue just to have a well-known todo list. I'm gonna gradually tackle these at time permits.

davetropeano commented 7 years ago

Selected tab stays active Button highlights in green Indicate current document in nav

I have code for these deployed to my staging environment from last week. I'll merge upstream later today and look at the simplest way to get the diff set implemented.

search box

Google custom search is likely the simplest thing to use here since it'll just be a snippet of JS

davetropeano commented 7 years ago

@geeknoid in moving to the new path based nav it looks like we lost some changes (at least that's my guess)

the tabs are no longer staying active when a document in the category is selected. I'll look at this
the current document is not highlighted in the left nav

I'll look at these

geeknoid commented 7 years ago

Dave, you said you had fixed those items a while ago, but I don't believe you ever submitted the changes to the repo...

davetropeano commented 7 years ago

@geeknoid Ahh... likely true. Some might not have work with the changes. Regardless, the above are done.

Also, just did a PR to change the large-ish search box and replace with a magnifying glass icon.

geeknoid commented 7 years ago

The site looks better and better every day. I've trimmed the list of items in this issue to reflect current reality.

davetropeano commented 7 years ago

We can collapse these:

Shrinking the browser window horizontally causes the search box to start overlapping the doc top nav bar. We probably want something cleaner there.

When shrinking the size of the browser window horizontally, we should be hiding the left-hand nav bar when things get tight.

To a single issue that we need the site to be usable on mobile devices. We need to choose whether we want to target iPads, iPad-mini, and/or phones. Basically we need to revisit where breakpoints in CSS are and whether responsive design pieces in Bootstrap were left out.

geeknoid commented 7 years ago

Updated to this morning's state.

geeknoid commented 7 years ago

Updated to latest state. This adds a few things, and takes a few things away...

davetropeano commented 7 years ago

The ALT text associated with images isn't being displayed. For example, if I go to >https://istio.io/docs/reference/what-is-istio/architecture.html and over my mouse over the >diagram, I don't see a tooltip.

there is no title attribute on the image. The use of the alt attribute for the tooltip is not cross-browser compatible (see https://developer.mozilla.org/en-US/docs/Defining_Cross-Browser_Tooltips).

geeknoid commented 7 years ago

Thanks, I've updated all uses of ALT with TITLE instead. Works great.

ldemailly commented 7 years ago

Edit: I was looking at an older version of the site, this has changed/mostly fixed alreday - though there is still more blank on the left than the right and for long lines the overlaid "copy" button is looking strange when mixed with underlying text

Adding:

(already mostly fixed) Fixed width isn't great (not sure how easy it is to change the style for variable width)

and related:

Some examples have long lines that you need to scroll for a while on the tiny box to see all of it, maybe should have \ inserted to become multiline with smaller width that fits (e.g. nodeport section of https://istio.io/docs/samples/bookinfo.html )

geeknoid commented 7 years ago

Are you seeing fixed width fonts outside of

blocks?

On Thu, May 4, 2017 at 2:23 PM, Laurent Demailly notifications@github.com wrote:

Adding:

Fixed width isn't great (not sure how easy it is to change the style for variable width)

and related:

Some examples have long lines that you need to scroll for a while on the tiny box to see all of it, maybe should have \ inserted to become multiline with smaller width that fits (e.g. nodeport section of https://istio.io/docs/samples/bookinfo.html https://istio.io/docs/samples/bookinfo.html )

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/istio/istio.github.io/issues/77#issuecomment-299313151, or mute the thread https://github.com/notifications/unsubscribe-auth/AVucHfJYW3oeGj4N4nSZu5hUcUazLMjMks5r2kHLgaJpZM4NLpM5 .

davetropeano commented 7 years ago

We should put the title of the current document in the top nav bar for reference. Between the sailboat and the top-right nav links, on every page except the landing page.

I think a better option is to put the title in an h1 tag at the top of the content. This aligns with nearly 100% of all blogs and doc sites I can think of.

Another idea might be to a) get rid of the tabs and replace with a dropdown menu under Docs, and b) implement breadcrumbs.

With breadcrumbs you would see the path of the current document. So something like Home > About or Home > Docs > Concepts > What is Istio?. Each segment is clickable. The advantage is that this takes up less screen real estate and is a pretty commonly seen thing

geeknoid commented 7 years ago

Breadcrumbs might be nice indeed. Worth exploring.

LisaFC commented 7 years ago

As per our chat, I think I still prefer the tabs - the breadcrumbs basically don't give you any navigation/orientation that the left nav doesn't so when the left nav is visible it's just duplicated info. The drop-down menu under Docs does provide horizontal navigation but is not particularly intuitive and makes that top bar look a bit weird.

Another thing that I think might look good is having (or just using, it might be in the cloned grpc.io stylesheets) a separate style for the "subheading"/description - "This page is about...", etc. Otherwise it looks a bit like an oddly short first paragraph.

louiscryan commented 7 years ago

Adding some items here

Font size for text is fixed in pixels which works poorly on high res screens. Suggest we switch to 12pt fo readability
Links in docs are hard to distinguish from plain text. Should increase font-weight to make more distinct

ldemailly commented 7 years ago

people are complaining about the \<copy> button/link:

[ ] it's transparent over text below which makes both hard to read (should have some background)
[ ] the examples often include the output of the command, which makes them un pastable as is - we should ideally split the command from the output (would look nicer too) - maybe we could put $ in front of command and copy would copy only lines with a $ ?

geeknoid commented 7 years ago

What do you mean by "the button/link"?

On Wed, May 10, 2017 at 12:20 PM, Laurent Demailly <notifications@github.com

wrote:

people are complaining about the button/link:

it's transparent over text below which makes both hard to read (should have some background)

the examples often include the output of the command, which makes them un pastable as is - we should ideally split the command from the output (would look nicer too) - maybe we could put $ in front of command and copy would copy only lines with a $ ?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/istio/istio.github.io/issues/77#issuecomment-300586034, or mute the thread https://github.com/notifications/unsubscribe-auth/AVucHRgttBsX0yC0gtW-nFtnVsAXdaMJks5r4g31gaJpZM4NLpM5 .

geeknoid commented 7 years ago

I'm closing this bug since it was getting too confusing. I've opened separate bugs to track outstanding issues.

I've pushed changes to systematically separate command-lines from their output, so I think that issue is taken care of. Regarding the button/link problem, I don't understand what that refers to so I didn't open another bug for that. Please go ahead and submit a separate bug with more detail on that issue. Thanks.

istio / istio.io

Few aesthetic things about the web site #77