Annotating table of content entries skipped level

Development
#1

Hello all,

In a table of content, when the level between two consecutive heading is more than one, a superfluous item marker is displayed for the skipped level.

For instance, for the following content:

{{toc/}}

= H1 =

=== H3 ===

The current result is
image
But should be
image

The proposed approach (see the PRs below) it to annotate skipped level with the nodirectchild class during rendering. And, to use this class to hide the item marker of those elements in css.

The main point to discuss is imo the choice of the css class which would become part of the macro API.
I’m currently proposing nodirectchild.

WDYT?

Jira issue: Loading...
Pulls requests:

#2

Hi.

For accessibility reasons there should be no skipped levels as to read here: Headings | Web Accessibility Initiative (WAI) | W3C.

We ourselves thought about that point whether to hide those bullet points not having a header. But we decided against it. We decided to give editors a chance to fix it because the toc will look ugly otherwise.

Regards, Simpel

#3

Hi Simple,

Thanks for your answer!

To keep you posted, in the absence of activity on this discussion I’ve merged what I proposed a few hours before your answer. As the next release is not too close, it is still time to improve this change though.

Your point is interesting but imo having a “bad” document structure should not have a impact on the document presentation in read mode.
What we could do though it highlight the nodirectchild bullets by having a visual clue in edit mode. To help editor spot the issue.

For instance, with the css below, the toc looks like this in edit mode when headings are skipped:

image

[contenteditable='true'] .wikitoc li.nodirectchild::before {
  content: "!";
  color: red;
  font-weight: bold;
  display: inline-block;
  width: 1em;
  margin-left: -1em;
  float: left;
}
#4

That’s a good idea. I like this kind of warning. Will this warning appear on empty headings too? (Some users try to style gaps between paragraphs with empty headings. That’s not good for screenreaders.)

#5

I’m not planning to do that part for now but please create an improvement issue on Jira :slight_smile:

1 Like
#6

I don’t agree with this. I’m -0 to hide this from the table of contents, for the reasons that @Simpel mentioned. On the contrary, I would make that missing heading more obvious, something like:

* H1
  * (missing)
    * H3

Thanks,
Marius

1 Like
#7

Imho we shouldn’t force users to create accessible documents (the same way we, e.g., don’t force users to enter a sensible alternative text for images even though images without useful alternative text are not accessible). While I agree it is good to push them, if a heading level is skipped for whatever reason, the TOC should still look nice for users viewing the document. Regarding the editor, this is different of course, I’m +1 for displaying a warning in the editor, though I think there should be more than an exclamation mark such that the user really understands what’s the problem.

Alternatively, we could add a “force accessibility” setting where we would, e.g., display errors for images without explicitly set alternative text (as the filename really isn’t a proper alternative text) and either display errors for missing headings or insert them automatically with some “(missing)” text such that editors are forced to fix them.

#8

I think users aren’t teached to use headers. They will use whatever will look nice. So +1 for a clear statement what’s wrong while in edit mode and have a nice view while reading only.

Second I like the idea of a “push accessibility” setting. Things like missing alt text, empty headers or wrong header levels could be “marked” and teached. Even empty paragraphs (2 new lines or more) could be easily avoided.

Maybe while this setting the ckeditor plugin a11ychecker then could be standard and one step further even started when saving. We have this plugin and aware people use it. I myself very aware of a11y forget things and I am lucky to be reminded.

#9

Thanks for your input. Given the close deadline (next Monday). We have different options:

  1. headings hidden in edit and view mode (the current implem.)
  2. headings are only hidden in view mode and are highlighted in red a proposed above

In addition, I’ll create improvement issues to:

  1. add better explanation on the red marks as proposed by @MichaelHamann
  2. generalize accessibility issues highlighting in edit mode as proposed by @Simpel

Here is my +1 for option 1

WDYT?

#10

+1 for 1
image

perhaps an option would be to only show the red marks in edit mode, don’t know if that’s technically feasible.

#11

It’s possible, this is what I proposed in a post above.

1 Like
#12

+1 for option 2. And thanks for the 2 improvement issues.

#13

Apologies, didnt read thoroughly enough!

I like my unoriginal idea that was your original idea!

1 Like
#14

Note that option 1 will be implemented for 15.2RC1.

I’ve created Loading... for the accessibility improvements.

If the default is not good, it is possible to overwrite it by using the .wikitoc li.nodirectchild CSS selector.

3 Likes