Readability and accessability suggestions for docs

I’m happy to have a proper look at this tomorrow. I’ve already addressed some other visibility issues and have just noted another one (line height on certain headings) so I’ll get to them all together.

2 Likes

We could limit max-width: 66rem to exclude code reference pages. This should work:

body:not(.single-wp-parser-function) #main {
   max-width: 66rem;
}

In case anyone is interested, I actually used this:

p,
body:not(.single-wp-parser-function):not(.single-wp-parser-hook):not(.single-wp-parser-class):not(.single-wp-parser-method) #main {
   max-width: 66rem;
}

That catches all the code pages. Without the p, regular text would revert to having too long a line length.

Interestingly, the WP code pages have the narrow width, even for the code, that we have now managed to move away from. So yay for us! :smile:

One other thing the WP code pages have is a table of contents, which shows up up at the top on narrow screen widths, and to the right of the regular text on wider screen widths. See e.g. saveDomDocument() | Function | WordPress Developer Resources Is this something we’d like to add?

If so, I’d like to see us have something more accessible than the ToC they have. I actually create ToCs for pages on several of my own sites, using GitHub - ivopetkov/html5-dom-document-php: A better HTML5 parser for PHP. and then run it through the_content filter. But it might be possible simply to use something like this instead (with the same filter, of course):

str_get_contents( $content, '<h2', '</h2>' );

I also do this on several sites.

1 Like

This is done by a plugin of which we have a copy. Maybe it could be amended to be more accessible.

What’s the name of the plugin? I tried several and found they were very poor, so built my own instead.

The main issue in this context is that there is nothing to tell the user that they are looking at a table of contents at all. If we continue to have no menu on the title bar, then we need simply to enclose the <h2> and <ul> tags within a <nav> tag.

If there is going to be a menu on the title bar (as I think there should be), then I would suggest that we change this:

<div class="table-of-contents">

to this:

<div class="table-of-contents" role="navigation" aria-labelledby="nav2">

We’d then also need to change the <h2> tag that follows to read:

<h2 id="nav2">

It’s Handbook Functionality for Pages. It is part of the stuff related to the parser.

See Create table-of-contents.php by KTS915 · Pull Request #7 · ClassicPress/site-docs · GitHub

2 Likes

All points of this thread are accomplished, inclusive ToC (on all but code ref post types).

Thus I think we can close?

3 Likes