A Perfect Table of Contents With HTML CSS

This article details building a robust and accessible table of contents (TOC) using only HTML and CSS, a surprisingly challenging yet rewarding endeavor. The goal was to create a TOC suitable for both web pages (with navigable links) and print media (books, brochures), handling multi-level headings gracefully.

Constructing a Table of Contents

A TOC's fundamental structure is simple: each entry links a section title to its page number, often with visual "leaders" (dots, dashes, etc.) connecting them. While readily generated in word processors, this wasn't feasible given an HTML-based workflow. The solution required an automated, HTML-compatible approach, ensuring accessibility and print-readiness.

Initial research revealed helpful but incomplete solutions. Julie Blanc's "Build a Table of Contents from your HTML" and Christoph Grabo's "Responsive TOC leader lines with CSS" provided valuable insights into layout techniques (float-based vs. CSS Grid), but neither perfectly addressed the requirements.

Optimal Markup Selection

Semantic correctness guided the markup choice. Initially, <table> and <code><dl></dl> were considered, representing the title-page number relationship as key-value pairs. However, these proved insufficient for multi-level TOCs (chapters and subsections). Nested <dl></dl> elements lacked semantic clarity.

The chosen approach leveraged an ordered list (<ol></ol>)—more appropriate than an unordered list (<ul></ul>) for the sequential nature of a TOC. The title-page number relationship was maintained by explicitly including "Page" before the page number within each list item. This simple addition clarifies the context, even without visual cues.

A basic HTML skeleton illustrates this:

<ol role="list">
  <li>
    <a href="https://www.php.cn/link/8f646834ef1adefaef52d74d5ea8329d">
      Chapter or Subsection Title Page 1
    </a>
    <ol role="list"></ol>
  </li>
</ol>

Styling the Table of Contents

Styling involved several steps:

1. Removing Auto-Generated Numbers: Manual numbering allows for unnumbered elements (forewords, etc.) common in books.

2. List Styling: The top-level list uses padding: 0 for alignment with paragraphs. Nested lists are indented using padding-inline-start: 2ch (character-width based padding for font independence). Crucially, role="list" was added to preserve list semantics in WebKit browsers when list-style-type: none is used.

3. Title and Page Number Styling: CSS Grid provided superior alignment, especially for multi-line titles. The grid's two columns (grid-template-columns: auto max-content) ensure the title expands to fill available space, while the page number (text-align: right) aligns to the right. The "Page" text is visually hidden using a visually-hidden class for accessibility.

4. Leader Implementation: The leader() CSS function, while specified, lacks browser support. The solution, borrowed from previous articles, utilizes a ::after pseudo-element with a long string of dots. However, this was improved for accessibility by wrapping the dots in an element with aria-hidden="true" to prevent screen readers from announcing the dots.

5. Finishing Touches: Top-level items are bolded (font-weight: bold), and a margin (margin-block-start: 1em) separates chapters from subsections. font-variant-numeric: tabular-nums and min-width: 2ch ensure consistent page number width across different digits for proper leader alignment.

The resulting CSS is efficient, flexible, and accessible, accommodating nested subsections without modification. The solution is equally effective for web navigation and print output. Credit is given to Julie Blanc, Christoph Grabo, and Sara Soueidan for their contributions and insights.

The above is the detailed content of A Perfect Table of Contents With HTML CSS. For more information, please follow other related articles on the PHP Chinese website!