A11y for ToC (table of contents)

[louismaximepiton]

Hi there,

I use Hugo since a year now, but I'm not very familiar with Go language. I haven't spotted any issue referencing this so :

I was working on accessibility in my project and I think I found an issue with the ToC generation regarding the links. Indeed, in my project, several links have the same label (in a migration guide) but, links that have the same label and have a different target should be avoided at all point since it could be confusing for screen-reader users.

So I was wondering if a solution could be bring here directly (I could try to handle that). Otherwise I think I can handle this in my project as well using partials/table-of-contents.html.

Issues

<nav id="TableOfContents">
  <ul>
    <li>
      <a href="#v1.0.0">v1.0.0</a>
      <ul><li><a href="#content">Content</a></li></ul>
    </li>
    <li>
      <a href="#v0.1.0">v0.1.0</a>
      <ul><li><a href="#content-1">Content</a></li></ul>
    </li>
  </ul>
</nav>

Expected

<nav id="TableOfContents" aria-label="Table of contents">
  <ul>
    <li>
      <a href="#v1.0.0">v1.0.0</a>
      <ul><li><a href="#content" aria-label="Content - v1.0.0">Content</a></li></ul>
    </li>
    <li>
      <a href="#v0.1.0">v0.1.0</a>
      <ul><li><a href="#content-1" aria-label="Content - v0.1.0">Content</a></li></ul>
    </li>
  </ul>
</nav>

Regards.

[nternetinspired]

It seems to me that this is a content issue. Even without a TOC, having the same headings in your document is confusing for all users, screen reader or not.

Solution, make your headings unique. It would improve the experience for all users.

[louismaximepiton]

Hey, thanks for taking some time to answer me !

You're totally right on this in most cases but I'm currently working on a migration guide in a technical documentation and I feel like people will be overflowed if I add some * - v1.0.0 on each title. Furthermore, I think that each migration guide is build this way (Version -> Category -> Subcategory -> etc..) so people might be used to it.

However, if you have any idea on how to name this kind of title, please feel free to propose anything for Components for example.

In a more general point of view, for the issue, does it mean that an option should be added to let people decide on each page which pages need such feature ?

[nternetinspired]

However, if you have any idea on how to name this kind of title, please feel free to propose anything for Components for example.

What is it that you think is wrong with your TOC html?

I've had a look at your site and both the TOC and page heading structure for the version sections seem good.

[louismaximepiton]

With a screen reader on the page you've seen, the links will be vocalized like:

• v5.2.2
• Components
• Forms
• Content
• Examples
• CSS and Sass variables
• v5.2.1
• Components
• ...
• Components

So as there isn't any structure or aria-label, many links will be vocalized the same way and lead to different parts of the page. My concern here is that it might be confusing/disturbing to have those links vocalized without the structure around or additional information like an aria-label.

[nternetinspired]

Right! I get you.

Screen reader users can already navigate directly to headings directly, so a TOC doesn't really add anything useful in that regard, it's just extra noise. The headings alone provide all the structure and functionality required.

Maybe it's better to set aria-hidden on your TOC container?

[louismaximepiton]

Hey there,

I was a bit busy later days, sorry for my late answer. Your solution might actually work for people using AT.

However, I had a discussion with an a11y expert and it seems, as you said first, that there isn't any issue with the actual implementation of Hugo because there's a structure around the links (<ul> and <li>s). According to this rule of WCAG. I'm closing this issue for now.

Thanks again for your time!

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.