This article is the nineteenth edition of the Advent of Patterns series. In this series, running from December 1st to December 24th 2024, I will document one design or programming pattern I have noticed recently. Read more about this series.
Tables of contents provide an overview of the contents of a document. Tables of contents can help a reader evaluate whether a page contains the information for which they are looking.
A table of contents may appear toward the top of an article, or in a sidebar. I have seen many sites use a sidebar on desktop devices to display tables of contents because there is more screen space available on desktop devices. On mobile, a section may appear at the top of an article with a label like “On this page” or “In this article”.
Here is an example of a table of contents displayed in the sidebar of the GitHub documentation:
This table of contents lists the sections of the document. This can be used to understand what information can be found on the page, and, by extension, whether a page contains the information for which you are looking.
On mobile, the table of contents appears at the top of the guide:
I find that tables of contents are especially useful on documentation websites, in formal writing, in technical writing, and any writing where there are several headings on a page.
Google Docs, a tool you can use to prepare documents, has an outline feature that shows a table of contents with all headings. This can be used to understand the heirarchy of the document – what headings you have and how they are structured.
Reflecting on this pattern, I noticed that GitHub’s “symbols” overview in text editing is similar to a table of contents. The symbols overview shows the functions, classes, and other pieces of information related to a program that can be identified through analyzing the file. Here is an example of a symbols overview of a file:
With this overview, I can:
- See what classes, functions, and constants are defined.
- Navigate to the line where a particular class, function, or constant is defined, or go to the start of the definition.
The symbols overview thus acts as navigation within a file, tailored to the structure of the code with which I am working. The functions defined within a class are nested visually, which gives me a visual indiction of the relationship between functions and classes.
When you click on a symbol, GitHub shows both the definition of the symbol and its references:
This can be used to help me understand how a defined constant or function is used throughout a file.
Like tables of contents, the symbol overview lets me understand, at a high level, what sections are in a file and how they relate. I can click on an item in the overview to skip to the definition of a particular constant or function or class and to see how it is used. This is like a table of contents where clicking on a heading takes you to the corresponding section.
In what places have you seen tables of contents? What are your favourite examples of this pattern?
