Site-www: 'Effective Dart' page issue - harder to navigate

[bencalabrese]

Page URL: https://www.dartlang.org/guides/language/effective-dart
Page source: https://github.com/dart-lang/site-www/tree/master/src/_guides/language/effective-dart/index.md

Found a typo? You can fix it yourself by going to the page source and clicking the pencil icon. Or finish creating this issue.

Description of issue:

I love a lot of the new design for the site, it looks very snazzy, but I'm having trouble navigating Effective Dart. There are a couple of issues in particular:

1. I'm finding it difficult to navigate between the major areas of Effective Dart. Specifically I'm missing the sub items that used to exist in the left nav panel. Without being too prescriptive, it seems like it would be great to give Effective Dart the same treatment as some other nav subitems like "Development > Command-line & server apps." Fixed

1. It's harder to see overview of issues in each major section (e.g. Style). Previously there was a table of contents on the right of the page as there is now, but there was _also_ a table of contents at the top of the page. The top table of contents was IMO much easier to read because of:
   
   
   
   • Larger indents of rules underneath their subcategories (e.g. Identifiers > DO name types using UpperCamelCase).
   
   
   • Less word wrap because of the greater width of the main section. Because the RHS table of contents is so narrow, a lot more scrolling needs to happen to see all of the rules.
   
   

[kwalrath]

Thanks for your feedback, @bencalabrese. I'd wondered about these things when we implemented the new site, so it's good to get your take on it.

We removed the in-page TOCs (#1602) due to a CSS issue, but we should be able to fix that.

[kwalrath]

I think that in the sidenav we want to have the following:

Effective Dart

• Overview (https://dart.dev/guides/language/effective-dart)
• Style
• Documentation
• ...

[arcra]

+1 I like the site, but personally I do find the TOC at the top to be extremely useful when reviewing code to follow the style guide.

I hope it can be added back to the top!

[bencalabrese]

That sounds great! Thanks @kwalrath!

[arcra]

Thanks for adding this!

I was trying it, and noticed that there's some weird rendering/behavior. The bullet points are not aligned with the text (but interestingly they also work as part of the link). Possibly related to the issue mentioned above?

In the attached screenshot, my mouse was where the red dot is at the level of the bullet point that for some reason is right above "Libraries", but (I hope) you can see that the link that it "corresponds" to (a couple lines below) is highlighted as if the mouse was hovering over it.

Can we re-open this issue? Or should I file a new one? What's the usual procedure?

[kwalrath]

I forgot that the formatting issue showed up on stable Chrome (which I don't normally use) but not on Canary. I'll take a look into this and see if it's an easy fix.

(Or anyone else is welcome to take a look... CSS is not my strong point.)

[kwalrath]

I wonder if this is an interaction with the code that makes links not be hidden by the always-visible black bar at the top of the page. I'm going to revert the TOC part of this change, for now, and leave this bug open so we'll remember to take a look later. (Or if someone can figure out a fix that works in both Chrome stable and Chrome canary, you're welcome to take a shot at it!)

Btw, the styles look different (not great, but readable) on Safari:

[kwalrath]

Removing the default TOC also removed the paper clip icons (which make it easy to get link anchors) from the page.

[kwalrath]

I'm going to close this issue because always having a top-of-page TOC isn't easy for us to implement, there are workarounds (make your window smaller, use the main page), and I suspect that people are now more used to the new navigation. Feel free to open a new issue if the lack of top-of-page TOC still really bugs you.