Customizing the table of content html in articles.

[MrLixm]

Hello,

Context: m.css is used with Pelican and .rst files.

Issue: I would like to know if it is possible to modify the hmtl generated to represent a table of content ? The current implementation wraps the toc in an <aside> container which I think should be <nav> ? Furthermore, the Contents title is created as an h3 while I think it should just be a <p> styled differently.

The html_sanity.py seems to be the responsible for producing the toc but I totally don't know how to modify to produce the desired result.

Cheers. Liam.

[mosra]

(Sorry for embarrassingly late replies, finally got a chance to get back to this project.)

Hi, good idea with the <nav> -- somehow I missed that opportunity when changing to HTML5 semantic tags. This is done in 295131dc8fa25a28914dccc8adb362cb81a7fdcc, and similarly changed from a <div> to a <nav> in the Doxygen and Python doc themes in 5e15cf3c579b79144be80afa8f2173b42f2a3d5a and 0df599eca35e155159965779860c8d79e42ade38. (The same change, changing from an <aside> to a <nav> went into vanilla Docutils 0.18, to have one more confirmation this is a good thing to do.)

About the <h3> I'm not sure -- according to MDN it's allowed inside <nav> and I feel it conveys the semantics better than just a <p>, it is a title/heading after all. I'll keep it that way.

[MrLixm]

Thanks for the answer and the quick fix ! For the h3 it's because most of the time it is a the top of the page so you go fromh1>h3>h2 when parsing heaeings which kind of break the flow. Not a big deal though. I'm not fluent enough with HTML to know if there is another class that carry a better meaning than <p>.

[mosra]

The way I understand it, for the semantic web (which matters mainly for screen readers and accessibililty features, and to some extent for tools that further process the page (like Reader Mode in Vivaldi, e.g.)), the most important is to have clearly marked what's the main part to focus on (<main> vs <header> / <footer>), what's the main content, how it's hierarchically organized and what are various extra pieces of information (<article>, <section> vs <aside>, etc), and where to find various navigation elements (<nav>).

Then, as a second step of "making sense of the content", for each of these blocks it's important to know what's a title and what's the actual content, while (in my understanding at least) it doesn't matter much if one uses <h1> or <h3> as the first element as long as all sub-headings (so, headings in the same block) are smaller.

[MrLixm]

My only source on info on this topic is this : https://www.a11yproject.com/checklist/#headings Which state that we should avoid breaking the heading orders I agree it should be a title but as far as I know we doesn't have a title class without an index ?

Anyway I don't think it's a big issue, if it take too much time to change might not be worth ? Cheers.

[mosra]

The info there is not detailed enough as it doesn't consider the case of various "side topics" / "asides" in the content, which is what the TOC is. With a different theme it could get extracted out of the page flow to a sidebar on the left, for example.

I think making the title a <p> and losing its semantic meaning would be a bigger crime than having headings in wrong order (<h1> -> <h3> -> <h2>) :)

To fix the order I suppose I could change the <h3> to a <h2> and then update the CSS style to make the text smaller again. But then there's various .. block:: and .. note:: directives that have a <h3> (or now <h2>) as well if you include a title, and those are meant to appear in any position on the page (say, inside a <h6> <section>), thus also breaking the heading order. If I would take the advice from that page to a point, I would have no general way to equip them with a title that is semantically a heading but doesn't break the order.

I don't know what's right, honestly, so I guess I'll just keep it as is until I come across a clear advice about this.