Style handbook with new O2 design

[chriscct7]

When the update to O2 was done to the make blog for meta, the template used on the homepage of that make blog wasn't copied over and as a result the side navigation bar used to navigate to all of the chapters of the handbook is missing

[samuelsidler]

Yeah... we haven't gotten to styling the handbook yet. But ​here are the mockups, if anyone's interested. :)

[kevinwhoffman]

I can help here. I don't have much experience contributing yet, but I have the skill set to write the CSS based on the mockups. Let me know what I can do.

[coffee2code]

In 3687:

Breathe: Add custom display handling for handbooks.

• Add template for single handbook pages.
• Add template for handbook-specific sidebar.
• Add basic styles (primarily for sidebar, handbook name link, header padding).

See #1825.

[coffee2code]

[3687] added template handling for handbook in the new o2 theme (Breathe) as well as basic styling support:

• Moved the sidebar to the left.
• Styled the handbook name link which was added to the top of the handbook pages.
• Adjusted some header spacing.

The mockups for the handbooks linked above don't cover all elements of a handbook page:

• Handbook name at top of handbook pages is omitted. I've carried over the link and its style from the P2 theme. Especially given the multi-handbook setup some sites may have, the handbook name should be present somewhere.
• Table of Contents is omitted and thus has no direction for its styling.
• I don't understand the first two mockups for the landing page. Is there not to be a sidebar for that page?

Significant styling needs at this time:

• The "chapters" sidebar widget: It only has default list styling and needs to match the mockup.
• The "Table of Content" in-page widget: It should probably look something like it does under the wporg-p2 theme, but the mockups don't provide any direction.
• The handbook page-to-page navigation links: The theme already has styling for navigation links, but the markup used by the handbook plugin is custom. We can modify the handbook plugin to output the expected classes and markup or within the theme we can duplicate/adapt the o2 styles with the existing markup. (Note: the navigation links output by the handbook plugin is used for both the p2 and o2 themes, so any changes there will need to be accounted for in the p2 theme).

@kevinwhoffman: Except for possibly the navigation links, the theme should be ready for you to make CSS and JS modifications to match the mockups. Let us know if you're still interested and have any questions.

[samuelsidler]

Replying to coffee2code:

• Handbook name at top of handbook pages is omitted. I've carried over the link and its style from the P2 theme. Especially given the multi-handbook setup some sites may have, the handbook name should be present somewhere.

I agree for multi-handbooks, but for most handbooks, it should be enough to style the subnav "Handbook" item as selected.

• Table of Contents is omitted and thus has no direction for its styling.

@mapk: Can you work up a style for Table of Contents? ​See the Topics box here.

• I don't understand the first two mockups for the landing page. Is there not to be a sidebar for that page?

Correct. It's going to be used as more of an introduction to the handbook and the team in general. I'll write up some content for the meta handbook.

• The handbook page-to-page navigation links: The theme already has styling for navigation links, but the markup used by the handbook plugin is custom. We can modify the handbook plugin to output the expected classes and markup or within the theme we can duplicate/adapt the o2 styles with the existing markup. (Note: the navigation links output by the handbook plugin is used for both the p2 and o2 themes, so any changes there will need to be accounted for in the p2 theme).

I prefer the mocked up page-to-page navigation style to the current ones, but they're not that different, are they? Looks like a different arrow to my eye, but the rest seems to be the same.

[kevinwhoffman]

A few requests to help me get started:

1. Provide a list of the CSS, JS, and PHP files that will affect these changes. I'm not sure if I am to work off of existing files or if I should provide my own CSS/JS to be merged later.
2. Provide a new complete set of mockups (sounds like there is still some debate regarding ToC).
3. Provide a list of example URLs to accompany each of the mockups (so I can see what they look like now vs. what they should look like).

[coffee2code]

Replying to samuelsidler:

I prefer the mocked up page-to-page navigation style to the current ones, but they're not that different, are they? Looks like a different arrow to my eye, but the rest seems to be the same.

Between the mockup and the existing handbook navigation, yeah, the main difference appears to be the arrow.

But I was referring to the page-to-page navigation style that is part of the p2-breathe theme. You can see it by editing the handbook nav links via browser dev tools to replace the <nav class="handbook-navigation" role="navigation"> block with something like:

<nav class="navigation" role="navigation">
	<h1 class="screen-reader-text">Handbook navigation</h1>
	<p class="nav-older">
		<a href="https://make.wordpress.org/meta/handbook/documentation/contributing-with-git/" rel="previous"><span class="meta-nav">←</span> Contributing With Git</a>
	</p>
	<p class="nav-newer">
		<a href="https://make.wordpress.org/meta/handbook/documentation/feature-plugin-treatment/" rel="next">Feature Plugin Treatment <span class="meta-nav">→</span></a>
	</p>
</nav>

It has a visible border above and between the nav links, and the nav links fill the full height (of their block) and 1/2 width of the main content div. See the attached screenshot​.

I don't mind whatever style is used; just noting that p2-breathe already has styling for nav links (that we'd just need to change our output markup to match-- or copy the CSS rules to specifically apply to the handbook nav markup -- if we wish to take advantage of them).

[coffee2code]

Example using p2-breathe default navigation styling for page-to-page navigation.

[coffee2code]

In 3709:

Breathe: Don't show the handbook name header when there's only the one handbook.

See #1825.

[coffee2code]

In 3710:

W.org P2 child theme: Don't show the handbook name header when there's only the one handbook.

See #1825.

[coffee2code]

In 3715:

Breathe: Don't show sidebar or handbook name header for handbook landing pages.

See #1825.

[coffee2code]

Replying to samuelsidler:

Replying to coffee2code:

• I don't understand the first two mockups for the landing page. Is there not to be a sidebar for that page?

Correct. It's going to be used as more of an introduction to the handbook and the team in general. I'll write up some content for the meta handbook.

I'm not a fan of this aspect of the design at all. The landing page effectively becomes a splash page that requires an additional click to get to the information most people want to get at. Sure, it'll have some helpful text, but it'll largely be introductory in nature and most relevant to people new to the handbook. For those seeking specific information, they now have to go to the handbook, then click past the landing page, then click to the topic of interest. Thumbs down from me.

That said, I implemented it in [3715] so it can be seen in action.

[coffee2code]

Also, the mockups lack design guidance for sites that have a submenu. For instance, see: ​https://make.wordpress.org/community/handbook/wordcamp-organizer/first-steps/budget-and-finances/. (Note that the "Handbooks" and "Meetups" menu items are dropdown menus.)

That page is a good source example containing elements not currently styled in the existing mockups (some previously mentioned upthread):

• Submenu (with dropdowns)
• Handbook name header (the "WordCamp Organizer Handbook" link at the top)
• Table of contents (here called "Topics")
• Subsections of the page (the h2 headers)

[coffee2code]

In 3751:

Breathe: Add basic styling for handbook page-to-page navigation links.

Copies styling from the W.org P2 child theme, which is largely how the mockups suggest them to look anyhow.

See #1825.

[coffee2code]

See also #1814 where the styling of the table of contents for the DevHub handbooks is being discussed. While the actually appearance may vary somewhat between the two, it would be nice to be consistent with at least the general link styling and accessibility considerations.

[ocean90]

In 4227:

Breathe: Add some basic styling for handbooks's "Table of Contents" box.

See #1825.

[ocean90]

In 4251:

Breathe: Show sidebar on handbook landing page.

See #1825.

[SergeyBiryukov]

Related: #2150

[pento]

In 4302:

Breathe: Add some styling for the the handbook "Chapters" menu.

See #1825.

[pento]

In 4628:

Breathe: Bring a shiny new style to the handbook Chapters menu.

Props mapk, pento.
See #1825.

[Kenshino]

Hey @pento

So a few things, the style is off - the arrows are not on the right

​https://cloudup.com/cM_h4MnSl6U as compared to the proposed ​http://codepen.io/mapk/pen/WRNjPy

Also the items are expanded at the get-go. Is that expected behaviour? It differs from code pen.

In the current setup, some are expanded by default and some are not.

Maybe a cache bust is needed?

[coffee2code]

@Kenshino: Cache did need busting, and has now been. I believe all your concerns have been addressed as a result.

[Kenshino]

@coffee2code

Thanks for the cache bust :)

The arrows are now entirely missing - ​https://make.wordpress.org/docs/handbook/

[coffee2code]

In 4635:

Breathe: Set explicit right CSS value for chapters menu expansion arrows.

See #1825.

[coffee2code]

@Kenshino: Try now.

Funny enough it worked for me without that rule I added, but then I was able to verify the issue outside of that particular setup. (It's late for me so I didn't investigate past the fix.)

[pento]

In 4652:

Breathe: Open the menu for the current handbook page using CSS instead of JS.

See #1825.

[pento]

In 4653:

Breathe: [4652] prevented the current menu from being closed, which is a fun, but defective, experience.

See #1825.

[samuelsidler]

I'm going to call this ticket fixed. Follow up issues should be filed as new tickets (I know I see a few things).