Document structure and headlines/Create specialised tables of contents

TODO: This page is under construction as part of the renewal of the "Document structure and headlines" documentation area. Feel free to improve, correct, or extend it where useful. (See: To-Do List)

1. When to use a specialised ToC

The standard table of contents is usually sufficient when the required result consists of:

number        title ........................ page

with ordinary variations in style, spacing, indentation, and selection.

A specialised ToC becomes useful when an entry must contain additional information or when the organisation of the list itself must change.

Typical cases include:

• changing the complete layout of each entry;
• adding an author, subtitle, or other metadata;
• nesting one list inside another;
• inserting list material that does not correspond to a structural head;
• creating a reusable combined list different from content ;
• horizontal or multi-column layouts.

The underlying model remains the same:

STRUCTURAL DATA
      │
      ▼
SELECTION
      │
      ▼
LIST ENTRIES
      │
      ▼
CUSTOM RENDERING

A specialised table of contents should therefore normally reuse document structure rather than create a parallel hierarchy solely for presentation.

2. Replace the complete entry with alternative=command

For complete control over the rendering of an ordinary list entry, use alternative=command.

The rendering command receives three arguments:

#1  structural number
#2  title
#3  page number

For example:

\define[3]\MyListEntry
  {#1\quad #2\hfill #3}

\setuplist
  [section]
  [alternative=command,
   command=\MyListEntry]

This makes the complete entry available to one renderer rather than formatting the number, text, and page components separately.

2.1. Example: put the page number before the title

A renderer can change the normal component order.

For example:

\define[3]\SectionListEntry
  {\par
   #3\quad #2
   \par}

\setuplist
  [section]
  [alternative=command,
   command=\SectionListEntry]

Here the page number (#3) is placed before the title (#2).

More elaborate typography can of course be added inside the rendering command.

3. Build a hierarchical ToC by nesting lists

A list can be placed while another list entry is being rendered.

A compact pattern is:

\placelist
  [chapter]
  [after={\placelist[section][criterium=local]}]

Conceptually:

Chapter One
   ├── Alpha
   └── Beta

Chapter Two
   ├── First
   └── Second

In this context, criterium=local has a specialised nested-list behaviour.

While an outer chapter entry is being rendered, that chapter supplies the structural context for the nested section list:

outer list entry
      │
      ▼
current outer chapter
      │
      ▼
\placelist[section][criterium=local]
      │
      ▼
sections belonging to that chapter

4. Add structural metadata to ToC entries

A structural head can carry user data in its second optional argument.

For example:

\startsection
  [title={A section with metadata}]
  [author={A. Uthor},
   subtitle={A subtitle}]

Text.

\stopsection

These values belong to the structural record.

When that record is rendered in a list, they can be accessed with:

\structurelistuservariable{author}
\structurelistuservariable{subtitle}

4.1. Add metadata with textcommand

A custom title renderer can combine the stored metadata with the normal title:

\define[1]\SectionTocEntry
  {\structurelistuservariable{author}\space
   --\space
   #1
   \space
   (\structurelistuservariable{subtitle})}

\setuplist
  [section]
  [textcommand=\SectionTocEntry]

This changes the list representation only.

The printed section head can remain:

1 A section with metadata

while the ToC entry becomes, for example:

1 A. Uthor – A section with metadata (A subtitle)

4.2. Avoid empty metadata fields

Not every structural item necessarily supplies the same user variables.

Use the raw accessor when the value must first be tested:

\rawstructurelistuservariable{author}

For example:

\define[1]\SectionTocEntry
  {\doifnot
     {\rawstructurelistuservariable{author}}
     {}
     {\structurelistuservariable{author}\space--\space}%
   #1%
   \doifnot
     {\rawstructurelistuservariable{subtitle}}
     {}
     {\space(\structurelistuservariable{subtitle})}}

This prevents separators or parentheses from appearing when the associated metadata is absent.

This behaviour was validated with current LMTX: metadata supplied for one section appeared in that section's ToC entry and did not leak into the following section without metadata.

5. Insert a manual list entry with \writetolist

Most ToC entries should originate from structural heads.

Sometimes, however, a list needs an entry that is deliberately not a new structural division.

For example:

\subject{Bibliography}

\writetolist
  [section]
  [location=here]
  {}
  {Bibliography}

The two final arguments provide the simple list entry's number and title fields.

Here the first field is empty, so no manual number is supplied.

Current LMTX also accepts the shorter form:

\writetolist
  [section]
  {}
  {Bibliography}

because location=here is the ordinary current-location case.

6. Insert material between list entries with \writebetweenlist

\writebetweenlist stores a command in the list stream rather than creating a numbered/title entry.

For example:

\writebetweenlist
  [section]
  {\blank[small]}

can insert spacing at the corresponding logical point when the list is later rendered.

An explicit location can also be supplied:

\writebetweenlist
  [section]
  [location=here]
  {\blank[small]}

A manual entry and inserted spacing can therefore be combined:

\writebetweenlist[section]{\blank}

\writetolist
  [section]
  [location=here]
  {}
  {Section under construction}

\writebetweenlist[section]{\blank}

Use these lower-level commands when direct manipulation of the list stream is genuinely required.

7. Define a reusable combined list

The standard content list is already defined by ConTeXt and should normally be configured with:

\setupcombinedlist
  [content]
  [...]

When another reusable combination is required, define a new combined list.

For example:

\definecombinedlist
  [summary]
  [chapter,section]

The new list can then be configured independently:

\setupcombinedlist
  [summary]
  [criterium=all,
   list={chapter,section}]

and placed with its generated placement command:

\placesummary

8. Historical specialised layouts

The ConTeXt Garden already contains specialised ToC examples that remain useful as sources of ideas:

• Horizontal table of contents
• Table of contents with fake columns

They illustrate layouts beyond the ordinary vertical number–title–page model.

Their implementations originate in older stages of ConTeXt documentation, so individual mechanisms should be checked against current LMTX before being reused unchanged.

8.1. Custom list alternatives

For layouts that cannot conveniently be expressed with the ordinary alternatives or with a simple alternative=command renderer, ConTeXt also provides custom list alternatives.

The general mechanism uses:

\definelistalternative
  [myalternative]
  [renderingsetup=list:myalternative]

together with a rendering setup:

\startsetups [list:myalternative]
  % custom rendering of the current list entry
\stopsetups

and then:

\setuplist
  [chapter]
  [alternative=myalternative]

This is an advanced interface. A custom alternative should normally be used only when the simpler list-rendering mechanisms do not provide enough control.

9. Related pages

For ordinary table-of-contents work:

• Table of contents

For controlling whether structural heads participate in the ToC:

• Include or exclude heads from the ToC

For the underlying structural model:

• Understanding document structure and section heads

For section-number representation:

• Section numbering

9.1. Command reference

• \setuplist
• \placelist
• \definecombinedlist
• \setupcombinedlist
• \writetolist
• \writebetweenlist
• \structurelistuservariable
• \rawstructurelistuservariable

10. Attribution and validation

This page collects advanced table-of-contents material that was separated from the general Table of contents HOW-TO during the renewal of the "Document structure and headlines" documentation area.

The following mechanisms were specifically validated with ConTeXt LMTX 2026.07.29:

• complete-entry rendering with alternative=command ;
• structural userdata used in individual list entries;
• nested chapter/section lists using criterium=local .

Manual list manipulation and older specialised layouts are documented separately so that their lower-level or historical character remains visible.