Move TOC to allow more space for the content

[grapplerulrich]

The content in the handbooks gets squashed between the Chapters and Table of Contents. This distracts the reader from the content.

An example for this can be seen on Theme Internationalization page. ​https://developer.wordpress.org/themes/functionality/localization/

There is whitespace to the left of the TOC that we can use. The screenshot above was taken on my 13" Mac so even on smaller screens there is extra space that we can use. On larger screens there would be much more.

[grapplerulrich]

Partially related to #1814

[samuelsidler]

I think that switching out the left navigation for the new one we have in the contributor handbooks will help a little, space-wise.

[mapk]

Working on some ideas here:

Current iteration (live):

PROS

• The sidebar nav is much easier to navigate now.
• Clearly identifies where the user is at.

CONS

• The content is still 'smushed' in between two floating navs.
• The grey and blue combo look a bit dated IMO.

Iteration v2:

PROS

• Left side nav is no longer floating.
• The break in page color gives a more 'extended' and 'airy' feeling to the page.
• In-page nav (Topics) is lighter (not so heavy), and doesn't feel overbearing.

CONS

• In-page nav (Topics) still smushes content. Still need to think this through.

[Ipstenu]

I like the left-side nav better when it's not floating. It makes it very clear what it is. A more 'static' navigation column.

In page topics is hard. Thinking about what I used to do in MediaWiki, this idea comes to mind.

Default it to where it is now. If someone uses a shortcode [show-toc] to something similar, DON'T show the ToC there, show it where the shortcode is. Allow for attributes like width=(PX|FULL) and float=(left|right) to allow for per-page customization and, if we had to, [show-toc no display] would hide it totally.

The reason that works in MediaWiki land is that the default works for most pages, but when it doesn't, the extra customization comes in handy.

• ​https://www.mediawiki.org/wiki/Manual:Table_of_contents
• ​https://www.mediawiki.org/wiki/Template:TOC

[grapplerulrich]

I like the left sided nav. It makes it a bit calmer. Just need to a find a solution for the right sidebar.

[samuelsidler]

I like the new left-side nav. And I like @Ipstenu's idea in comment:5 about how we can handle the topics box without actually removing it.

[mapk]

In 4758:

Breathe: Handbook sidebar nav redesign.

The floating sidebar nav was causing readability issues and so I redesigned it to be anchored better and be more evident that it's a sidebar nav. Also redesigned the Topic in-page box to be lighter so it doesn't detract from the content as much. Still working on a better solution.

Props grapplerulrich

See #2389, #2410

[mapk]

In 4760:

Breathe: Highlighted 'active' nav item fix.

The 'active' menu item was not highlighting correctly on ​https://make.wordpress.org/training/handbook/about/getting-started/, so rather than relying on jQuery to make it work, I just added a CSS selector instead which works correctly now.

Props samuelsidler

See #2389, #2410

[coffee2code]

In 4790:

Breate: Fix display of handbook name (seen in multi-handbook sites) after changes in [4789].

See #2389.

[karmatosed]

@mapk what is the current state on this? Is it being rolled out, complete and ok to close?

[mapk]

@karmatosed I think we're good to go, but it hasn't been implemented across the board. For example, the use case in the ticket subscription hasn't adopted the new design.

[karmatosed]

@mapk cool...so how should we go about doing that?

[mapk]

Replying to karmatosed:

@mapk cool...so how should we go about doing that?

I'm really not sure. Either @samuelsidler helped with that, or the team contributors did. Maybe @pento or @coffee2code might have an idea?

[samuelsidler]

Looks like we need a patch for devhub.

[karmatosed]

Removing feedback labels as this just needs a patch.

[coffee2code]

Example handbook page from ticket, as it looks today (2018-11-20)

[coffee2code]

Mockup of proposal to move ToC into sidebar from 20.

[coffee2code]

As a follow-up, [6512] (from 10 months ago) actually implemented the handbook sidebar nav redesign introduced in this ticket, bringing the design of DevHub's handbooks in line with the Make sites.

However, it doesn't affect the reported issue much at all. See current screenshot of same example page from ticket​. The left sidebar looks nicer and functions nicely, but the main content is still sandwiched between the sidebar and a long TOC. Though it does seem like it ever so slightly has a little more main content width.

In addition to Ipstenu's idea of a TOC shortcode, another possible approach is to make the TOC a sidebar widget. Placed above the handbook menu, and perhaps (partially) collapsed by default. Otherwise, same behavior as the existing handbook sidebar menu. See mockup​ of how this could look. The mockup initially hides all child elements.

[DrewAPicture]

Moving the TOC into the sidebar has merit, I like that a lot and I think other similarly-designed software does it too, so there's precedent (see: Help Scout).

[dufresnesteven]

I also think adding topics in the sidebar is a fair solution.

Adding an alternate solution to the discussion....

We could also consider having the topics inline:

Assumptions:

• Development handbooks are typically quick references
• Development handbooks make use of anchors links for navigations within and from external locations (Ie in a search response) to specific sections within the document
• We are not going to extend the max-width of the site container past 960px.

Pros

• Since we typically use descriptive titles, it helps to contextualize the document
• Doesn't restrict the actual content (as it currently does)
• Layouts would be similar for all device sizes

Cons

• Articles with a lot of linkable content will have a large topic section
• On Mobile, it may take a few swipes to get to the content if you know what you are looking for and are not making use of the anchor links.

[coffee2code]

Screenshot of handbook page with ToC under new theme

[coffee2code]

The DevHub theme has somewhat recently been completely changed. The new theme provides a much wider main content area, even if the table of contents is present.

The example page referenced in the ticket is currently bare due to the content having been relocated. But the ​new location for that content demonstrates how the new theme greatly accommodates this request (see latest attachment​.

As such, this request should be considered fulfilled.