Widen site grid

[j-low]

[description]:

• widen overall site grid
• move TOC to righthand gutter
• implement fixed and independently-scrollable sidenav

[cockroach-teamcity]

This change is 

[j-low]

cc: @jseldess @lhirata @rmloveland @Amruta-Ranade

This first build implements the independently-scrollable sidenav which is QA-able at this point. I have not merged or duplicated the other sidenav changes from the work performed last week.

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/ed965d2defcd15b4807c20577b71d92ae5f997b9/

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/6498294b90f95b1699c1a24ae8254701d57f3a3e/

[jseldess]

Scrollable sidenav looks to be working great, @j-low. I don't see the page toc moved to the right gutter, though. Is that still coming?

[lnhsingh]

For the independently scrolling side nav, is there a way to lock the minimum size of the sidebar container? What I'm noticing is that it gets squished when you scroll down to the bottom of the main content / footer.

For example:

Let me know if you need clarification!

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/209a9cd6b36d4809d23959914dc85f3ea9fb29d1/

[rmloveland]

Hey @j-low thanks for working on this! Really looking forward to a wider layout on the site.

Unfortunately I have one issue: The new layout causes the content text not to wrap to fit inside the browser window when the browser is using half the screen in a "2-up" configuration with another app (screenshot attached).

In other words, it seems like this layout really wants the browser to be full-screened or at least prefer to be a horizontal rectangle rather than a vertical rectangle. I suspect this might break for some developers who read docs on a vertical monitor (something I've seen around), or for people like me who work in side-by-side windows.

[j-low]

@rmloveland thanks for the QA! That's actually a known issue that's being worked on. It just didn't make it into the last commit.

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/440bc9dc167f666cadf4a58a47f1ada6c33a55f3/

[j-low]

Ignore that last commit message; that was meant for a Hugo commit. There is another update coming with the actual QA feedback implemented.

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/ec2a58c6a800a33ff21f5dbff680912aa4bc66a2/

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/ffe40a53f16e043aa0ec834a8beeb5cf517f8fc1/

[j-low]

The most recent build represents the first version ready for QA. There are a few judgment calls I made we should discuss, e.g.:

• I added a check for a no_toc variable in the front matter to hide/show the righthand TOC column (there might be a more ideal way of doing this)
• Below 1072px the right hand TOC goes away and is instead rendered in its old position; this is because the screen real estate begins to get very narrow and those extra gutter pixels are needed to maintain a functional layout.

There are likely other things that will probably come up in the QA process but perhaps we can have a brief stakeholder check-in early next week to run through it all.

[rmloveland]

@j-low I love the new layout! The highest compliment I can pay is this: once this is out I can stop using my custom page-widening CSS for the site (which was sorta broken anyway as I'm not a developer). Thank you!

[jseldess]

This is looking awesome, @j-low!

A few observations and requests:

• I think we should experiment with removing the bullets in the toc, as seen in docs like this: https://developers.google.com/identity/protocols/OAuth2UserAgent. I think the toc line space could be tightened somewhat, too.
• In cases where the toc is longer than the screen, you can't get to the bottom of the toc unless you scroll to the bottom of the page. Example: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/ffe40a53f16e043aa0ec834a8beeb5cf517f8fc1/stable/recommended-production-settings.html. I think in this case (toc is longer than screen), we should use a scrollbar. Example: https://developers.google.com/identity/protocols/googlescopes
• I think while we're doing this, we might as well reduce the whitespace between the sidenav and the main content, and between the topnav and the rest of the page. Especially now that we're using so much horizontal space, the padding feels excessive. I don't mean to focus on them at the exclusion of all others, but the google docs referenced above are a lot tighter than ours.
• With the toc in the right gutter, the green background highlighting also feels strange. What do you think about using a left border like we currently do for nested selected items in the sidenav. Also an example: https://firebase.google.com/docs/android/setup

[j-low]

@jseldess great stuff, thanks for the feedback. I like all the suggestions. The one about removing the green background @kuanluo had also suggested too but I had forgotten to remove it in this PR. Bullets can definitely go. I will experiment with making the TOC itself scrollable as well as removing all the extra whitespace. I will notify the docs channel when the PR is updated.

One question re: the green background: do we want it to be removed when the screen is resized and the TOC is rendered in the original area?

@rmloveland glad this all seems to be an improvement!

[kuanluo]

@j-low @jseldess I echo all of Jesse's feedback.

Re: the green background: do we want it to be removed when the screen is resized and the TOC is rendered in the original area?

When the screen is resized and TOC is rendered in the original area, we can also get rid of the green background, depend on the way it's redesigned. In Firebase's case, for example, the right blue sidebar works well in smaller screens.

Reduce the whitespace between the sidenav and the main content, and between the topnav and the rest of the page. Especially now that we're using so much horizontal space, the padding feels excessive.

Agreed. @j-low and I discussed further tweaks to reduce the whitespace, as well as the line-height.

What do you think about using a left border like we currently do for nested selected items in the sidenav. Also an example: https://firebase.google.com/docs/android/setup

Yes.

@j-low, can you tweak the look and feel of the TOC and see how it goes?

• Remove the green background & bullet points.
• Add the vertical line on the secondary bullets, like the side nav. The first level items don't need the line.
• Reduce line-height to 14px.
• Move the TOC down to top-align with Overview, or whatever the first H1 is.

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/edbb71ef49db42a78f2744c32e5600e79e4388ba/

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/a4ec85fbfb9395c45ab25e0cdc12b7e8182b57ee/

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/ad9fb9947fe1cd8ba3e8e66a2e9c4d809f2c0420/

[j-low]

@jseldess PR updated with the changes we discussed earlier (e.g. TOC sub-item highlighting, merge conflicts resolved; first tier nav items default to open on all versions).

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/7d2881f5f63741cd016d6d4cd7976c83f673af79/

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/e52e52f12e27aadaf6b1491ecf459ad9e4900c33/

[lnhsingh]

This looks great!

One minor thing I noticed is when you use search, the version toggle disappears. Since the search is limited to the selected version, it would be helpful to have an indicator of what version you're looking at.

[j-low]

@lhirata I believe that feature bug has been in place for some time. I think this is something we could tackle in the near-ish future. @jseldess and I spoke about it a few months ago in the context of a broader discussion about better visibility around versioning-- search results page included.

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/21917ceb7450d5bbe1cacd34457d53997fc34d58/

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/fbefd60bbc478e6916be520b06b75cf7d3c4838c/

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/a2d2d8c20238350c15d74571fedf1f3bc88c6a61/

[jseldess]

@j-low, all pages now either have toc: true or toc: false. You can now put in log to show the toc in the right column only if toc: true.

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/84e2044bdfd12d6ae5c4f682b1e064307784d449/

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/0ff705f22264bfeae1e44d9692995af1b40c01c4/

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/78b6e753765327237036c5ffd29f4465de3e646e/