Restructure single template to follow a better DOM structure for A11Y

[alexstine]

The largest change places the sidebar after the closing </main> for better ARIA landmark support/DOM structure for accessibility. Many visual regressions will be caused by this PR, hoping Meta Team can help out with CSS adjustments.

Screenshots

Before	After
image	image

How to test the changes in this Pull Request:

1. Open a single doc article.
2. Notice the sidebar is moved.
3. Notice meta information appears just below the main heading 1/article title.

[ryelle]

The table of contents sidebar actually stays in the right place, visually, so that's good 🙂

I don't think we want to move the meta to the top of the article, that was put at the end intentionally in the design. Same with flipping the search box below the "In this article" section. If you can update this to simply move the aside group, though, we can probably get that merged fairly quickly.

[ryelle]

Actually, I just remembered why the markup was done this way— on small screens, the table of contents should appear between the heading & the content.

@WordPress/meta-design What do you think of flipping the content & ToC on small screens? It would look roughly like this:

@alexstine Could you also explain why these improvements are better for accessibility?

[alexstine]

@ryelle

I don't think we want to move the meta to the top of the article, that was put at the end intentionally in the design.

This info is not really discoverable where it currently sits. Just underneath the article title would be a big improvement.

Could you also explain why these improvements are better for accessibility?

This is better because of how ARIA landmarks currently work in screen readers. Picture this HTML structure.

<main>
<aside></aside>
</main>
<footer></footer>

When a screen reader user jumps by landmarks, it helps them find important sections of the page. My example above uses HTML5 tags just like the docs site does. The HTML5 specification as shown above maps to the following ARIA roles: main, complementary, and contentinfo. Anyway, back to the point. In the current state of things, If I navigate by landmark, I will get main content, then the sidebar, then the footer. This is why it is always better to leave the aside outside of the main. Having nested landmarks does not improve the navigation experience.

Does this make sense? Can record a quick video if not. Before and after.

Thanks.

[jasmussen]

Definitely one we need to solve. Thinking through the flow, I do wonder how useful the table of contents will be for someone browsing on a mobile device, if it sits at the end. My instinct would be that on mobile, it should sit at the top mainly so that you can jump to sections without having to swipe a lot.

Would it be feasible to find a design that let it sit at the top, but in a collapsed manner? Perhaps not a details/summary combo, but something like it?

[alexstine]

@jasmussen I agree. Having the table of contents collapsed below the main heading would be a suitable solution. I just really do not want the presentation of a sidebar in the main content.

@ryelle Is the table of contents block specific to this site or is this going to require a global change .org wide?

[ryelle]

Having the table of contents collapsed below the main heading would be a suitable solution. I just really do not want the presentation of a sidebar in the main content.

Would the solution be to not use the aside wrapper if we collapse it?

Is the table of contents block specific to this site or is this going to require a global change .org wide?

The block itself is site-wide (in the wporg-mu-plugins repo). It's currently only used on this site, but it's been suggested that it would be useful on other sites as we roll out the redesign. Hopefully if we land on a good page structure here, we can reuse that layout for other sites as well.

[alexstine]

@ryelle

Would the solution be to not use the aside wrapper if we collapse it?

Correct.

Okay, let me go figure out how this block currently works and see if I can make an easy PR for it.

Thanks.

[adamwoodnz]

Worth noting that it is not usually that complicated to reorder content visually (using flex or grid) as long as the HTML structure is fairly flat. Sounds like we're looking to remove nesting which is helpful.

[alexstine]

@ryelle @jasmussen Moved the table of contents out of the sidebar and below the document meta. This will not be really testable as this is now a dependency on the upstream plugin. Hopefully this gives some idea as to how it may look visually.

[fcoveram]

Here is an idea that taps into what @jasmussen suggested

Mobile

Desktop

In both desktop and mobile the text style of TOC heading and anchor links are the same, and ul has a different padding to be aligned with the heading. On mobile, padding values are different to reach a visual balance with the expand / collapse action.

---

What do you think of this idea?

[ryelle]

In #63, the sidebar container was updated and now uses a plain div. It's still right after the article heading, but at least it's not an aside anymore. That's been merged, so you can try it, for example on Introduction to Blogging.

The ability to expand/collapse the table of contents is being discussed in WordPress/wporg-mu-plugins#389.

With that, I'm going to close this PR, as the two links above should cover everything. If I missed something let me know & we can re-open or open a new issue as needed.

[alexstine]

I still wonder if "Search documentation" form can be moved to somewhere else. Maybe make it apart of the banner landmark just after the main navigation? Having search documentation form after the main document title does not make much sense. I agree this related change removing the complementary landmark was good.

[ryelle]

Visually, the search form is part of the sidebar, so we can't move it without changing the page layout somehow… so that's a question for @WordPress/meta-design.

Maybe make it apart of the banner landmark just after the main navigation?

Is that the global header (the part that's the same on all sites)? There's already the global site search, which searches all of wordpress.org, in that section (it is confusing that there are two search forms, but this one that's currently in the sidebar/after the header searches just the documentation site).

[alexstine]

It would be nice if the search form for docs could be in the sidebar, it makes sense there but will look odd if that is the only thing in the sidebar. Placed after the main title does not make any sense unfortunately. It may visually but this would not appear where screen readers would expect. Any chance that global search in the future can be improved to have a combo box? E.g. search whole site, search docs, search X, etc?

[StevenDufresne]

Any chance that global search in the future can be improved to have a combo box? E.g. search whole site, search docs, search X, etc?

This idea is somewhat relevant to the discussion about suggesting terms in the dropdown: WordPress/wporg-mu-plugins#367.