WordPress.org

Making WordPress.org

Opened 3 years ago

Closed 3 years ago

#1825 closed task (fixed)

Style handbook with new O2 design

Reported by: chriscct7 Owned by:
Milestone: Priority: high
Component: Make (Get Involved) / P2 Keywords:
Cc:

Description

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

Attachments (1)

meta-1825.p2-breathe-nav.png (77.8 KB) - added by coffee2code 3 years ago.
Example using p2-breathe default navigation styling for page-to-page navigation.

Download all attachments as: .zip

Change History (31)

#1 @samuelsidler
3 years ago

  • Priority changed from normal to high
  • Summary changed from Since O2 upgrade Meta Handbook is missing the sidebar to Style handbook with new O2 design
  • Type changed from defect to task

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

#2 @kevinwhoffman
3 years ago

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.

#3 @coffee2code
3 years ago

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.

#4 follow-up: @coffee2code
3 years ago

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

#5 in reply to: ↑ 4 ; follow-ups: @samuelsidler
3 years ago

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.

#6 @kevinwhoffman
3 years ago

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

#7 in reply to: ↑ 5 @coffee2code
3 years ago

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

Last edited 3 years ago by coffee2code (previous) (diff)

@coffee2code
3 years ago

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

#8 @coffee2code
3 years ago

In 3709:

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

See #1825.

#9 @coffee2code
3 years ago

In 3710:

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

See #1825.

#10 @coffee2code
3 years ago

In 3715:

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

See #1825.

#11 in reply to: ↑ 5 @coffee2code
3 years ago

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.

#12 @coffee2code
3 years ago

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)

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


3 years ago

#14 @coffee2code
3 years ago

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.

This ticket was mentioned in Slack in #meta-devhub by coffee2code. View the logs.


3 years ago

#16 @coffee2code
3 years ago

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.

#17 @ocean90
3 years ago

In 4227:

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

See #1825.

#18 @ocean90
3 years ago

In 4251:

Breathe: Show sidebar on handbook landing page.

See #1825.

#20 @pento
3 years ago

In 4302:

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

See #1825.

This ticket was mentioned in Slack in #wptv by sam. View the logs.


3 years ago

#22 @pento
3 years ago

In 4628:

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

Props mapk, pento.
See #1825.

#23 @Kenshino
3 years ago

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?

#24 @coffee2code
3 years ago

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

#25 @Kenshino
3 years ago

@coffee2code

Thanks for the cache bust :)

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

#26 @coffee2code
3 years ago

In 4635:

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

See #1825.

#27 @coffee2code
3 years ago

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

Last edited 3 years ago by coffee2code (previous) (diff)

#28 @pento
3 years ago

In 4652:

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

See #1825.

#29 @pento
3 years ago

In 4653:

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

See #1825.

#30 @samuelsidler
3 years ago

  • Resolution set to fixed
  • Status changed from new to closed

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

Note: See TracTickets for help on using tickets.