What sort of markup do you recommend for a table of contents?

Question

I need to create a large table of contents for an HTML book but I can't decide what's the best solution for its markup. I have two options in mind: definitions lists or ordered lists.

Would you consider this a personal style decision? And how about semantics?

I like my list to be numbered but I have problems using "ol" with nestes lists. I guess I'd do the same thing I did with my definition lists by numbering manually (and disabling style in my list).

I thought of these two:

Option A:

<div class="TOC">
    <dl>
        <dt><a href="#">Preface</a></dt>
        <dt>I. <a href="#">Chapter 1</a></dt>
        <dd>
            <dl>
                <dt>1 <a href="#">Section 1</a></dt>
                <dd>
                    <dl>
                        <dt>1.1 <a href="#">Subsection A</a></dt>
                        <dt>1.2 <a href="#">Subsection B</a></dt>
                        <dt>1.3 <a href="#">Subsection C</a></dt>
                    </dl>
                    <dt>2 <a href="#">Section 2</a></dt>
                </dd>
            </dl>
        </dd>
    </dl>
</div>

Option B:

<div class="TOC">
    <ol>
        <li><a href="#">Preface</a></li>
        <li><a href="#">Chapter 1</a>
            <ol>
                <li><a href="#">Section 1</a>
                    <ol>
                        <li><a href="#">Subsection A</a></li>
                        <li><a href="#">Subsection B</a></li>
                        <li><a href="#">Subsection C</a></li>
                    </ol>
                </li>
                <li><a href="#">Section 2</a></li>
            </ol>
        </li>
    </ol>
</div>

Answer 1

Ordered list is the correct markup. Using a definition list would imply that the major section title is a term which is defined by the titles of its subsections, which is not quite correct.

Answer 2

2020 opinion...

Use <nav> to indicate navigation

• <nav> implies role=navigation
• <div role="navigation"> is decent but <nav> is ideal
• <nav> should have heading or else [aria-label] to tell purpose

Use <ol> or <ul> to group links

• Use <ol> for TOC about sequential content like book chapters
• Use <ul> for TOC about nonsequential content like an FAQ

TOC semantic markup examples

<nav>
  <h2>Chapters</h2>
  <ol>
    <li><a href="#chapter-1">Chapter 1</a>
    <li><a href="#chapter-2">Chapter 2</a>
    <li><a href="#chapter-3">Chapter 3</a>
  </ol>
</nav>

<nav aria-label="Chapters">
  <ol>
    <li><a href="#chapter-1">Chapter 1</a>
    <li><a href="#chapter-2">Chapter 2</a>
    <li><a href="#chapter-3">Chapter 3</a>
  </ol>
</nav>

<nav>
  <h2>Questions</h2>
  <ul>
    <li><a href="#money">How do artists get paid?</a>
    <li><a href="#feedback">How do artists get feedback?</a>
    <li><a href="#fans">How do artists get fans?</a>
  </ul>
</nav>

<nav aria-label="Questions">
  <ul>
    <li><a href="#money">How do artists get paid?</a>
    <li><a href="#feedback">How do artists get feedback?</a>
    <li><a href="#fans">How do artists get fans?</a>
  </ul>
</nav>

Answer 3

Definition lists are NOT strictly for "definitions" as some people seem to be saying - if they were they would have extremely few uses. However, while <dl/>s are very flexible and have many uses, the ordered-list does seem like a better option here.

If you're trying to number nested lists (whether they're nested <ol/>s or <dl/>s), you can use CSS counter-increment and counter-reset properties to add numbers automatically based on the nested depth, rather than maintaining the numbering manually for every revision.

Example:

.TOC ol{
  list-style-type:none;
  counter-reset:toc1;
}

.TOC ol li::before{
  content:counter(toc1)' ';
  counter-increment:toc1;
}

.TOC ol li ol{
  counter-reset:toc2;
}

.TOC ol li ol li::before{
  content:counter(toc1)' .'counter(toc2)' ';
  counter-increment:toc2;
}

.TOC ol li ol li ol{
  counter-reset:toc3;
}

.TOC ol li ol li ol li::before{
  content:counter(toc1)' .'counter(toc2)' .'counter(toc3)' ';
  counter-increment:toc3;
}

Answer 4

100% I'd go with ordered list. This is exactly what they were put into the language for. Using definition lists is an abuse of the language, just because their default rendering is somewhat like you want to see. (Use CSS to make it like right)

What problem are you having with nested ordered lists? (You aren't even supposed to nest DLs)