Sections, titles and tables of contents

This lesson’s report has seven headings, and after its first pdfLaTeX run the contents list shows none of them. Its PDF has no title either, although “Monsoon Notes” is printed at the top of the page.

Below you will number headings in both systems and leave some unnumbered, list them in a contents list of the depth you choose, put the title on the page and into the PDF’s metadata, and keep the heading levels in the order screen readers rely on. A second pdfLaTeX run and one package fix the report; Typst gets all of it right in one compile.

Headings are commands in LaTeX and equals signs in Typst

Here is the report in both systems: an unnumbered preface, two sections, subsections under them and one heading a level deeper. It uses A5 pages, so its contents list reads back in short lines:

% sections.tex: a short report with an unnumbered preface and three levels of headings.
\documentclass[a5paper]{article}
\title{Monsoon Notes}
\author{A. Rao}
\date{}% no date under the title
\setcounter{tocdepth}{2}% list sections and subsections, not subsubsections
\begin{document}
\maketitle
\tableofcontents
\section*{Preface}
\addcontentsline{toc}{section}{Preface}
Why these notes exist.
\section{Rainfall}
\subsection{Gauges}
\subsubsection{Daily readings}
Two days are missing.
\subsection{Totals}
\section{Rivers}
\subsection{Flow}
\end{document}

// sections.typ: the same report in Typst.
#set page(paper: "a5")
#set document(title: [Monsoon Notes], author: "A. Rao")
#set heading(numbering: "1.1")
#title()
#outline(depth: 2)

#heading(numbering: none)[Preface]
Why these notes exist.

= Rainfall
== Gauges
=== Daily readings
Two days are missing.
== Totals
= Rivers
== Flow

In LaTeX a heading is a sectioning commandsectioning command: A LaTeX command that starts a heading at one level, such as \section or \subsection. Its level number decides whether the heading is numbered (secnumdepth) and whether the table of contents lists it (tocdepth).. The LaTeX2e reference manual gives each a level number: \section is 1, \subsection 2 and \subsubsection 3, then come \paragraph and \subparagraph; above them, \chapter is 0 in report and book, which alone have it, and \part is −1 there and 0 in article. Whether a level is numbered depends on the counter secnumdepth, which the manual gives as 3 in article and 2 in report and book: an article numbers three levels.

Typst writes headings with equals signs, = for level 1, == for level 2 and so on. Its reference adds the difference that surprises people coming from LaTeX: headings are not numbered until you ask, because numbering defaults to none. #set heading(numbering: "1.1") asks for numbers like 1, 1.1 and 1.1.1. This session builds both files; read the headings in the first PDF and at the end of the Typst one:

from session import files, run

# The report's two pdfLaTeX runs, with the .toc file written between them, then the same report in Typst. pdftotext
# reads the start of each PDF, keeping the layout; rows of leader dots are shortened to " …" so that lines fit.
files("sections/sections.tex", "sections/sections.typ")
run(r"""
pdflatex -interaction=nonstopmode sections.tex | grep -E "Warning|Output"
pdftotext -layout sections.pdf - | head -14
cat sections.toc
pdflatex -interaction=nonstopmode sections.tex | grep -E "Warning|Output"
pdftotext -layout sections.pdf - | head -14
typst compile sections.typ sections-typst.pdf
pdftotext -layout sections-typst.pdf - | head -16
""", mask=[(r"( \.){3,}", " …")])

$ pdflatex -interaction=nonstopmode sections.tex | grep -E "Warning|Output"
Output written on sections.pdf (2 pages, 58284 bytes).
$ pdftotext -layout sections.pdf - | head -14
                   Monsoon Notes
                          A. Rao


Contents

Preface
Why these notes exist.


1       Rainfall
1.1     Gauges
1.1.1    Daily readings
Two days are missing.
$ cat sections.toc
\contentsline {section}{Preface}{1}{}%
\contentsline {section}{\numberline {1}Rainfall}{1}{}%
\contentsline {subsection}{\numberline {1.1}Gauges}{1}{}%
\contentsline {subsubsection}{\numberline {1.1.1}Daily readings}{1}{}%
\contentsline {subsection}{\numberline {1.2}Totals}{2}{}%
\contentsline {section}{\numberline {2}Rivers}{2}{}%
\contentsline {subsection}{\numberline {2.1}Flow}{2}{}%
$ pdflatex -interaction=nonstopmode sections.tex | grep -E "Warning|Output"
Output written on sections.pdf (2 pages, 60239 bytes).
$ pdftotext -layout sections.pdf - | head -14
                   Monsoon Notes
                            A. Rao


Contents
Preface                                                        1

1 Rainfall                                                     1
  1.1 Gauges …   1
  1.2 Totals …   2

2 Rivers                                                       2
  2.1 Flow …   2

$ typst compile sections.typ sections-typst.pdf
$ pdftotext -layout sections-typst.pdf - | head -16
Monsoon Notes
Contents
Preface … ⁠1
1 Rainfall … ⁠1
  1.1 Gauges … ⁠1
  1.2 Totals … ⁠1
2 Rivers … ⁠1
  2.1 Flow … ⁠1

Preface
Why these notes exist.

1 Rainfall
1.1 Gauges
1.1.1 Daily readings
Two days are missing.

Both systems numbered the same way: 1 Rainfall, 1.1 Gauges, 1.1.1 Daily readings, then 1.2, 2 and 2.1. Step through the headings to see each count go up, start again or stay where it was:

An unnumbered heading can still be listed in the contents

A preface, an abstract or acknowledgements usually carry no number. LaTeX’s starred form, \section*{Preface}, does this, and the reference manual says what else it does: it does not number the heading and does not make an entry in the table of contents. The report adds the entry by hand with \addcontentsline{toc}{section}{Preface}, in the form the manual gives for that command. Typst’s #heading(numbering: none)[Preface] is unnumbered too, but the reference says headings are listed in the outline unless outlined is false, so Typst needs no extra line.

Both contents lists in the session start with “Preface”, with no number in front. The heading after it was numbered 1, not 2, in both systems: an unnumbered heading changes no count. For a long heading, LaTeX’s optional argument, \section[Rain]{Rainfall at the three stations}, gives the contents and the page headers a shorter title. The three cases side by side:

The contents list takes two runs in LaTeX and one compile in Typst

\tableofcontents prints the contents where it stands, and the reference manual explains why it needs a second run: LaTeX stores the entries in a .toc file during one run and reads them back on the next, so after the first run of a new document only the heading appears. That is what the session’s first PDF showed: the word “Contents” and nothing under it. The .toc file printed after that run holds one \contentsline for every heading, Daily readings included, and the second run turned those lines into the list. Follow one heading through both runs:

The depth is a separate setting. The tocdepthtocdepth: The LaTeX counter that sets the deepest heading level the table of contents lists, as in \setcounter{tocdepth}{2}. Its partner secnumdepth sets the deepest level that is numbered. counter names the deepest level listed: \setcounter{tocdepth}{2} in the report lists sections and subsections, so the third-level heading Daily readings was numbered in the text but left out of the contents. Typst’s #outline(depth: 2) does the same, and the reference says that with the default, none, every heading is included.

Count the levels before you choose a depth. In article, \section is level 1, as = is in Typst, so depth 2 lists the same headings in both. In report and book, \chapter is level 0, so tocdepth 2 reaches \subsection, three levels down, while Typst’s depth 2 still stops at ==.

The title belongs on the page and in the PDF’s metadata

A PDF has two places for a title: the page, where readers see it, and its metadataPDF metadata: What a PDF records about itself, such as its title and author, which viewers show in the window title and pdfinfo prints. LaTeX writes it through hyperref, Typst through set document., which search tools read and a viewer can show in its title bar. In LaTeX, \title, \author and \maketitle fill only the first. The reference manual adds a detail about the date: if you omit \date, LaTeX prints the current one, and \date{} prints none, which is why the report has it. This session reads the metadata of each PDF with pdfinfo:

from session import files, read, run, write

# Where the title of the report goes: pdfinfo reads the PDF's metadata, first of the plain LaTeX build, then of a copy
# that loads hyperref with pdfusetitle, then of the Typst build.
files("sections/sections.tex", "sections/sections.typ")
write("sections-meta.tex", read("sections.tex").replace(
    "% no date under the title\n",
    "% no date under the title\n\\usepackage[pdfusetitle]{hyperref}% the title and author into the PDF's metadata\n"))
run(r"""
pdflatex -interaction=nonstopmode sections.tex | grep -E "Output"
pdfinfo sections.pdf | grep -E "^(Title|Author|Pages)"
grep -n "hyperref" sections-meta.tex
pdflatex -interaction=nonstopmode sections-meta.tex | grep -E "Output"
pdflatex -interaction=nonstopmode sections-meta.tex | grep -E "Output"
pdfinfo sections-meta.pdf | grep -E "^(Title|Author|Pages)"
typst compile sections.typ sections-typst.pdf
pdfinfo sections-typst.pdf | grep -E "^(Title|Author|Pages)"
""")

$ pdflatex -interaction=nonstopmode sections.tex | grep -E "Output"
Output written on sections.pdf (2 pages, 58284 bytes).
$ pdfinfo sections.pdf | grep -E "^(Title|Author|Pages)"
Pages:           2
$ grep -n "hyperref" sections-meta.tex
6:\usepackage[pdfusetitle]{hyperref}% the title and author into the PDF's metadata
$ pdflatex -interaction=nonstopmode sections-meta.tex | grep -E "Output"
Output written on sections-meta.pdf (2 pages, 58807 bytes).
$ pdflatex -interaction=nonstopmode sections-meta.tex | grep -E "Output"
Output written on sections-meta.pdf (2 pages, 61348 bytes).
$ pdfinfo sections-meta.pdf | grep -E "^(Title|Author|Pages)"
Title:           Monsoon Notes
Author:          A. Rao
Pages:           2
$ typst compile sections.typ sections-typst.pdf
$ pdfinfo sections-typst.pdf | grep -E "^(Title|Author|Pages)"
Title:           Monsoon Notes
Author:          A. Rao
Pages:           1

The plain LaTeX build printed “Monsoon Notes” on the page, yet pdfinfo found no Title and no Author. The copy that loads hyperref with the option pdfusetitle, which its manual says derives the PDF’s title and author from \title and \author, had both. You can also set them yourself with \hypersetup{pdftitle={…}, pdfauthor={…}}.

Typst keeps one title for both places. #set document(title: [Monsoon Notes], author: "A. Rao") writes the metadata, and the reference says that by default the title is not shown on the page; #title(), the title element, prints it. Typst’s accessibility guide asks for that set rule before any content, and pdfinfo found the title and author in the Typst PDF.

Screen readers follow the headings, so levels must not skip

Heading levels are a map: screen readers list the headings to jump between them, and tagged PDF stores each one with its level. Typst’s accessibility guide gives two rules for that map. Never use a heading for your document title; use the title element instead. Never skip a heading level when going deeper.

Each of these three files breaks one rule. This session puts them through Typst’s export for PDF/UA-1, the standard for accessible PDF, which --pdf-standard ua-1 asks for:

// heading-title.typ: the title typed as a level 1 heading, and no document title set.
#set text(lang: "en")
= Monsoon Notes
== Rainfall
Gauges were read every morning.

// heading-meta.typ: the title set for the PDF's metadata, and still typed as a level 1 heading.
#set document(title: [Monsoon Notes])
#set text(lang: "en")
= Monsoon Notes
== Rainfall
Gauges were read every morning.

// skipped.typ: a title, then a heading two levels below the one before it.
#set document(title: [Monsoon Notes])
#set text(lang: "en")
#title()
= Rainfall
=== Daily readings
Two days are missing.

from session import files, run

# Typst's PDF/UA-1 export against the two rules of its accessibility guide: heading-title.typ types its title as a
# level 1 heading and sets no document title, heading-meta.typ sets the document title and still types it as a
# heading, and skipped.typ goes from = straight to ===. Last, skipped.typ compiled without the standard.
files("title/heading-title.typ", "title/heading-meta.typ", "title/skipped.typ")
run(r"""
!typst compile --pdf-standard ua-1 heading-title.typ
typst compile --pdf-standard ua-1 heading-meta.typ
!typst compile --pdf-standard ua-1 skipped.typ
typst compile skipped.typ
""")

$ typst compile --pdf-standard ua-1 heading-title.typ
error: PDF/UA-1 error: missing document title
 = hint: set the title with `set document(title: [...])`

[exit status 1]
$ typst compile --pdf-standard ua-1 heading-meta.typ
$ typst compile --pdf-standard ua-1 skipped.typ
error: PDF/UA-1 error: skipped from heading level 1 to 3
  ┌─ skipped.typ:6:0
  │
6 │ === Daily readings
  │ ^^^^^^^^^^^^^^^^^^
  │
  = hint: heading levels must be consecutive

[exit status 1]
$ typst compile skipped.typ

heading-title.typ, whose title is a level 1 heading and which sets no document title, stopped with PDF/UA-1 error: missing document title. heading-meta.typ sets the document title and still types it as a level 1 heading, and the export accepted it without a word: the check finds a missing title, not a heading used as one, so the first rule is yours to keep. skipped.typ, which goes from = straight to ===, stopped with skipped from heading level 1 to 3 and the hint that heading levels must be consecutive. Compiled without the standard, the same file built without a word, so a skipped level is easy to miss.

Practise: outline a report

Number the headings of a report and list them to a depth, exactly as both systems did above. The sample tests use this lesson’s report, and the first hint is open:

def contents(headings, depth):
    """Return the contents lines for a list of (level, title, numbered) headings, down to the given depth."""
    # Replace this comment: count each level, number the numbered headings, and keep those at depth or less.
    return [title for level, title, numbered in headings]

from contents import contents

REPORT = [
    (1, "Preface", False),
    (1, "Rainfall", True),
    (2, "Gauges", True),
    (3, "Daily readings", True),
    (2, "Totals", True),
    (1, "Rivers", True),
    (2, "Flow", True),
]


def test_the_report_to_depth_2():
    """lists the lesson's report as both systems did with depth 2"""
    assert contents(REPORT, 2) == ["Preface", "1 Rainfall", "1.1 Gauges", "1.2 Totals", "2 Rivers", "2.1 Flow"]


def test_the_report_to_depth_1():
    """lists only the top level with depth 1"""
    assert contents(REPORT, 1) == ["Preface", "1 Rainfall", "2 Rivers"]


def test_the_report_to_depth_3():
    """numbers a third level as 1.1.1"""
    assert contents(REPORT, 3)[3] == "1.1.1 Daily readings"


def test_unnumbered_heading_changes_no_count():
    """keeps counting across an unnumbered heading of the same level"""
    headings = [(1, "Rain", True), (2, "Gauges", True), (1, "Notes", False), (2, "Totals", True)]
    assert contents(headings, 2) == ["1 Rain", "1.1 Gauges", "Notes", "1.2 Totals"]


def test_deeper_counts_start_again():
    """starts the subsection count again after each section"""
    headings = [(1, "A", True), (2, "x", True), (2, "y", True), (1, "B", True), (2, "z", True)]
    assert contents(headings, 2) == ["1 A", "1.1 x", "1.2 y", "2 B", "2.1 z"]

Then try the questions on headings, contents and titles. They start with the part you know least, and a question about levels or depth that you miss comes back once before the end:

Interview questions

Warm-up (fresher to 2–5 years): how does \section* differ from a Typst heading with numbering: none?

Both print a heading without a number, and neither changes the count, so the next numbered heading continues where the last one left off. They differ in the contents list. LaTeX’s starred form also leaves the heading out of the table of contents, and with hyperref it gets no bookmark; to list it, add \addcontentsline{toc}{section}{Preface} right after it. A Typst heading with numbering: none stays in the outline, because outlined is true by default; to drop it, add outlined: false. So a preface listed in the contents takes two lines in LaTeX and one in Typst, and a heading kept out of the contents takes one line in LaTeX and needs outlined: false in Typst.

Two harder questions follow, about a university’s rules for the contents and title of a thesis and about an accessibility check that fails. Decide where you would start before you open each first step:

Key takeaways

• LaTeX headings are sectioning commands with level numbers, numbered down to secnumdepth; Typst headings are = signs, numbered only after #set heading(numbering: "1.1").
• A starred LaTeX heading has no number and no contents entry until \addcontentsline; a Typst heading without numbering stays in the outline unless outlined is false, and neither changes the count.
• \tableofcontents fills in on the second run, from the .toc file; tocdepth and Typst’s outline(depth:) set how many levels are listed, counted from level 0 for chapters in LaTeX.
• \maketitle prints the title, but only hyperref (pdfusetitle or pdftitle) puts it into the PDF’s metadata; Typst’s set document writes the metadata and #title() prints it.
• Use the title element for the title and never skip a heading level: Typst’s PDF/UA-1 export stops on a missing document title and on a skipped level, but a heading typed as the title is yours to catch.