Add pre/post config to ToC

[uPagge]

According to the html5 standard, there must be a title in the nav tag. However, the TOC is generated without the ability to specify this header

It should be like this. This helps visually impaired browsers to read what this section is responsible for.

<nav>
  <h1>Navigation</h1>
  <ol>
    <li></li>
    <li></li>
  </ol>
</nav>

P.S. If you wish, you can make sure that this is done in Google. They add an h tag for the sections while hiding it, since it is only needed for semantic markup.

[uPagge]

In any case, reference to the standard

https://html.spec.whatwg.org/multipage/sections.html#the-nav-element

Even though there is one example there where the h tag is not used in nav. It is considered best practice to add a title. It would be great if you provided such an opportunity.

[davidsneighbour]

It' the first time I am reading that the standard requires a title tag. It doesn't, and h1 is NOT a title tag. It's the topmost header tag and the standard suggests to have only one in one single document. That's a suggestion. Having an h1 in an automatically created TOC makes no sense for 99% of pages and adding an h1 title to a nav that isn't even the sites main navigation will result not only in SEO issues but issues in all parsers that try to build a structure from your page.

Not sure where you got that from, the only reason I would expect some form of title, but then in form of an title-attribute, would be for a11y if the navigation is not the main navigation.

[uPagge]

Perhaps the problem is in my English, please forgive me in advance, as I have to use a translator. An error in translation, it does not require a title, but an h tag. This is optional for the nav, but it is good practice as screen readers will be able to read this section for people with vision problems.

Originally in the html5 spec there was no such thing as h1-h6, there was only an h tag. And the numbering remained only for backward compatibility with html4

If you look at the specification, you will see that more than one h1 tag can be used and the document is considered valid in html5.

https://html.spec.whatwg.org/#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements

Problems with parsers arise now, because the nav section does not have an h tag, instead of a heading there is "Untitled Section"

"Not sure where you got that from"

From html5 spec

[davidsneighbour]

Screenreader: aria-title attribute on the nav tag. Sorry, but what you want is really something that might have been thought about 10 years ago but is not part of the "living standard" of HTML. It's a specific use case for your project, I understand, but making it accessible means using aria-attributes on the tags, not adding more tags inside.

[jmooring]

Perhaps an approach where one could override the HTML that encapsulates the outer <ul>...<\ul>

Then you could do:

[markup]
  [markup.tableOfContents]
    pre = "<nav id="TableOfContents"><h1>Something</h1>"
    post = "</nav>"

Or set the values to blank if you want to do the encapsulation within a template:

[markup]
  [markup.tableOfContents]
    pre = ""
    post = ""

There's precedent for the pre and post approach with Menu Entry Variables.

[uPagge]

@jmooring Oh, thanks a lot, I will definitely try this way

[jmooring]

This was a suggestion for a software enhancement. It is not an active feature.

[bep]

@jmooring good suggestion. We do also have an issue about exposing the ToC as a data structure, allowing people to have their own templates, but I guess this is a easy improvement.

[nternetinspired]

I'd suggest that aria-label may be more appropriate in this situation, given that it's addition will not visually affect existing sites. In additon, I would suggest that an ordered list, <ol> is a better choice for a table of contents as the order in which the items are presented does matter, the content author explicitly defined that order and presenting the items in a different order (as you can with an unordered list) would affect the meaning.

:100: should not be an <h1>!

[uPagge]

@nternetinspired You are correct about the order, but this can already be changed using configuration.

markup:
  tableOfContents:
    ordered: true

[nternetinspired]

…yes, but I'd argue that the default should semantically correct.

[jmooring]

...yes, but I'd argue that changing the default would break a lot of sites. Those who want ordered list have already configured their sites accordingly.

[nternetinspired]

It would fix a lot of sites. Using an unordered list for a table of contents is incorrect. Changing that may lead to some minor visual changes but document structure and accessibility would be improved.

Just my $0.02 and I'm more than happy to leave it at that. As already pointed out, I can correct the semantics of my own sites quite easily, but I believe it would be preferable for those with less experience to not have to. My general preferance will always be for ‘better by default’.

[davidsneighbour]

Yep, let's leave it at that. There is no such thing as a TOC in HTML. Using a list for an overview of headings is not intended. Be it unordered or ordered. In the current HTML standard the nearest that would come to something like a TOC would be a nav element with subsequent links to the sections of the page. If one of these links would have child-sections then some form of sub-division is required. which could be a div or a list or whatever element you find fitting.

Having the TOC as data structure will solve all these issues and keeps Hugo out of religious conversations (like this one).

[jmooring]

@davidsneighbour,

I respect the ideas and concerns raised by both @uPagge and @nternetinspired. The title of this issue is "Add pre/post config to ToC" and it has been flagged as a "GoodFirstIssue." If we are going to take a swing at incremental improvement before implementing TOC as a data structure (which has been open for 31 months) then conversations like this are important and healthy.

For the record, I agree with @nternetinspired. If you are going to use list items to display a table of contents, then the list items should be ordered. I just don't want to break existing sites without a really good reason.

Out of curiosity I looked at a few higher-profile Hugo sites (digital.gov, getbootstrap.com, kubernetes.io), and they would all be visually impacted by a <ul> to <ol> TOC change. Of those three sites, digital.gov would see the most change.

Before

After

[uPagge]

In fact, I find it strange that as a developer I cannot influence this area and make it the way I want it.

It seems to me that adding a similar feature is an excellent solution to this problem.

[markup]
  [markup.tableOfContents]
    pre = ""
    post = ""

By default, you can leave it as it is generated now, but give the opportunity to override this behavior.

[nternetinspired]

Apologies if my comments have ruffled feathers, that was never my intention. I am often direct and tone-of-voice does not easily transfer to type. I should have introduced myself!

Hi 👋 I'm Seth. I try to make user-centric sites, both professionally and in my free time. I love Hugo and I'd like to contribute where I can.

@jmooring Thanks. Agree, there would be a significant, not minor, change visually. My primary concern was a11y and UX.

[bep]

We're not changing the default.

[xbc5]

I was directed here for my issue (#10371), which is somewhat related.

In addition: if you don't want to change the default (for any reason) perhaps create a new behaviour, and eventually (possibly) deprecate the old one.

[zoe-translates]

I'd suggest that aria-label may be more appropriate in this situation, given that it's addition will not visually affect existing sites.

And an alternative would be aria-labelledby, which, if support, will be super handy. The reason is that it is very common to find the <nav> for the ToC in such document structure --

<h1 id="toc-heading">Table of Contents (or whatever text appropriate)</h1> <!-- or other suitable heading level -->
<!-- this is the Hugo-generated nav element for ToC -->
<nav id="TableOfContents"> <!-- !!!!! -->
</nav>

It would be super nice if we as site/template authors can replace the line marked by !!!!! as the following

<nav id="TableOfContents" aria-labelledby="toc-heading">
<!-- here "toc-heading" is the user-configurable id referring to the element that describes what this nav is for -->

I believe this is the most semantically-consistent and simple way to distinguish the ToC <nav> from any other <nav>s on the page. By reusing the id as the value of aria-labelledby, we are less likely to duplicate things that essentially do the same thing (describing the nav).

The ability to label the ToC <nav> is desirable because it is highly likely that the page contains at least one other <nav> element (e.g. menu, breadcrumb navigation, etc.). Without clear and distinct labels, it will be confusing to the assistive technology.

[bep]

Since Hugo 0.111.0 we no have a data structure that can be used to create custom ToCs. The documentation may miss good examples for this, but I'm sure that will happen in a day or two.

[Paul-Stern]

Hello everyone! My name is Paul, I'm a newcomer here and I would like to contribute to this issue. The issue is open but a quick look at the discussion above casts some doubts whether it still needs any work to be done. So is it supposed to make any changes to the project's code about this issue now? I am asking as I was looking for an issue for my first contributions and found this one.