Heading levels in Markdown table of contents #1778
Description
So I'm not sure if this is at all possible, or what the best way would be to do this, but we're having some issues using the .TableOfContents variable in templates.
There are a couple of points:
- Semantically, HTML should only have one
<h1>tag per section root. - It would be nice to have the top-level, i.e.,
<body>-level,<h1>tag generated in the layout template using the.Titleattribute of the page. (It works better semantically, rather than having the title in two places.) - When rendering Markdown, the table of contents in
.TableOfContents, sensibly, only renders navigation for the headers in the actual content. - Furthermore, the
.TableOfContentsalways treats<h1>as top-level, even if there are no<h1>-level headers.
Because of this, if you comply with (1) and implement (2), and thus only have <h2> or lower headers in your content, the generated table of contents contains an empty top-level <nav> as a result of (3) and (4).
Example table of contents:
<nav id="TableOfContents">
<ul>
<li>
<ul>
<li><a href="#introduction:e95c9b0e3cf17661856239295171d427">Introduction</a></li>
<li><a href="#at-a-glance:e95c9b0e3cf17661856239295171d427">At a Glance</a></li>
</ul>
</li>
</ul>
</nav>This messes with the page semantically since now the navigation has an empty top-level. The way I see it there are two ways to fix this:
- Somehow get the header tags in layout templates into the table of contents, so the top-level is not blank.
- Get the renderer to remove empty levels, e.g., by treating
<h2>as top-level headers if there is no<h1>in the content.
I'm not sure if there is currently an undocumented workaround to implement either of these solutions. But if there isn't, would there be a way to allow for using either of the two solutions to achieve a more semantic table of contents?