Opened 7 years ago

Last modified 4 years ago

#2389 new defect (bug)

Move TOC to allow more space for the content

Reported by: grapplerulrich's profile grapplerulrich Owned by:
Milestone: Priority: normal
Component: Handbooks Keywords: ui-feedback has-screenshots


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.

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.

Attachments (3)

meta-2389.20181120-current.png (270.3 KB) - added by coffee2code 5 years ago.
Example handbook page from ticket, as it looks today (2018-11-20)
meta-2389.toc-in-sidebar.png (190.0 KB) - added by coffee2code 5 years ago.
Mockup of proposal to move ToC into sidebar from 20.
Screen Shot 2019-12-03 at 1.45.18 PM.png (427.2 KB) - added by dufresnesteven 4 years ago.

Download all attachments as: .zip

Change History (27)

#1 @grapplerulrich
7 years ago

Partially related to #1814

#2 @samuelsidler
7 years ago

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

#3 @mapk
7 years ago

Working on some ideas here:

Current iteration (live):


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


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

Iteration v2:


  • 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.


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

This ticket was mentioned in Slack in #meta by mapk. View the logs.

7 years ago

#5 @Ipstenu
7 years ago

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.

#6 @grapplerulrich
7 years ago

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

#7 @samuelsidler
7 years ago

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.

This ticket was mentioned in Slack in #forums by ipstenu. View the logs.

7 years ago

#9 @mapk
7 years ago

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

#10 @mapk
7 years ago

In 4760:

Breathe: Highlighted 'active' nav item fix.

The 'active' menu item was not highlighting correctly on, 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

This ticket was mentioned in Slack in #meta by mapk. View the logs.

7 years ago

#12 @coffee2code
7 years ago

In 4790:

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

See #2389.

#13 @karmatosed
7 years ago

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

#14 @mapk
7 years ago

@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.

#15 follow-up: @karmatosed
7 years ago

@mapk how should we go about doing that?

#16 in reply to: ↑ 15 @mapk
7 years ago

Replying to karmatosed:

@mapk 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?

#17 @samuelsidler
7 years ago

Looks like we need a patch for devhub.

This ticket was mentioned in Slack in #design by karmatosed. View the logs.

6 years ago

#19 @karmatosed
6 years ago

  • Keywords ui-feedback ux-feedback removed

Removing feedback labels as this just needs a patch.

5 years ago

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

5 years ago

Mockup of proposal to move ToC into sidebar from 20.

#20 @coffee2code
5 years ago

  • Keywords ui-feedback has-screenshots added

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.

#21 @DrewAPicture
5 years ago

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).

This ticket was mentioned in Slack in #docs by ibdz. View the logs.

5 years ago

#23 @dufresnesteven
4 years ago

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:


  • 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.


  • 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


  • 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.
Last edited 4 years ago by dufresnesteven (previous) (diff)

This ticket was mentioned in Slack in #design by estelaris. View the logs.

4 years ago

Note: See TracTickets for help on using tickets.