Toc rendering is not clean enough #186
Description
Zine Version
v0.10.2
Steps to Reproduce
Source
The source Structured Markdown (smd) begins with H2 headers, adhering to the best practice of reserving H1 for the page title. The layout file uses the $page.toc() function.
---
.title = "Homepage",
.date = @date("2020-07-06T00:00:00"),
.author = "Sample Author",
.layout = "sections.shtml",
.draft = false,
---
## One
## Two<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title :text="$site.title"></title>
</head>
<body>
<h1 :text="$page.title"></h1>
<div>
<h2>-- TABLE OF CONTENTS --</h2>
<ctx :html="$page.toc()"></ctx>
</div>
</body>
</html>Diff Analysis: Current vs. Desired TOC Output
The current rendering incorrectly introduces an outer <ul><li> wrapper for the missing H1 level, which is a structural defect. The desired output correctly lists the H2 items directly at the top level of the TOC list.
--- Current Output
+++ Desired Output
@@ -10,8 +10,7 @@
<div>
<h2>-- TABLE OF CONTENTS --</h2>
<ul>
-<li>
-<ul><li>
-One</li><li>Two</li></ul></ul>
+<li>One</li>
+<li>Two</li>
+</ul>
</div>
<div :loop="$page.contentSections()">
<h2>-- SECTION BEGIN --</h2>Describe the issue
The current implementation of Table of Contents (TOC) rendering typically begins its structure at the H1 level. However, from a best practices perspective in modern web development, it is strongly recommended that document content, particularly in Markdown and subsequent HTML, should begin with H2 to strictly adhere to the principle of a single H1 element per page. This avoids semantic and accessibility issues associated with multiple H1s.
A significant problem arises when a Markdown document follows this best practice by starting with H2 (or a lower level) and intentionally omits an H1 header: The generated TOC exhibits an incorrect structure.
Instead of directly starting the table with the H2 sections, the TOC rendering mechanism inappropriately inserts an empty and unnecessary level 1 list item (<li>). This empty element acts as a placeholder for the missing H1, incorrectly wrapping the actual list of H2 headings and corrupting the logical hierarchy of the resulting TOC.