LilyPond Notation Reference: 3.2.6 Table of contents

### 3.2.6 Table of contents

A table of contents is included using the `\markuplist \table-of-contents` command. The elements which should appear in the table of contents are entered with the `\tocItem` command, which may be used either at top-level, or inside a music expression.

    \markuplist \table-of-contents
    \pageBreak

    \tocItem \markup "First score"
    \score {
      {
        c'4  % ...
        \tocItem \markup "Some particular point in the first score"
        d'4  % ...
      }
    }

    \tocItem \markup "Second score"
    \score {
      {
        e'4 % ...
        \tocItem actI \markup "Act I"
        f'4 % ...
        \tocItem actI.sceneI \markup "Scene 1"
        g'4 % ...
        \tocItem actI.sceneI.recitativo \markup "Recit."
        a'4 % ...
      }
    }

Optionally, a label can be associated with a particular item, or a hierarchical list of existing labels, finishing with that item’s label. That latter case allows to mark the item as a ‘child’ of the preceeding labeled items, thus making the score’s structure apparent in the table of contents.

Markups used for formatting the table of contents are defined in the `\paper` block. There are three ‘pre-defined’ markups already available;

- `tocTitleMarkup`

  Used for formatting the title of the table of contents.

      tocTitleMarkup = \markup \huge \column {
        \fill-line { \null "Table of Contents" \null }
        \null
      }

- `tocItemMarkup`

  Used for formatting the elements within the table of contents.

      tocItemMarkup = \markup \fill-line {
        \fromproperty #'toc:text \fromproperty #'toc:page
      }

- `tocFormatMarkup`

  How the table’s top level entries will be formatted (if there are several hierarchical levels). This is actually a procedure, as explained in Markup construction in Scheme.

      tocFormatMarkup = #make-bold-markup

- `tocIndentMarkup`

  Used to define how the outline’s hierarchy will be made apparent. This markup is printed zero, one or several times depending on the level of each entry.

      tocIndentMarkup = \markup \hspace #4

Any of these variables can be changed.

Here is an example translating the table of contents’ title into French:

    \paper {
      tocTitleMarkup = \markup \huge \column {
        \fill-line { \null "Table des matières" \null }
        \hspace #1
      }

Here is an example changing the font-size of the elements in the table of contents:

    tocItemMarkup = \markup \large \fill-line {
      \fromproperty #'toc:text \fromproperty #'toc:page
    }

Note how the element text and page numbers are referred to in the `tocItemMarkup` definition.

The `\tocItemWithDotsMarkup` command can be included within the `tocItemMarkup` to fill the line, between a table of contents item and its corresponding page number, with dots:

    \header { tagline = ##f }
    \paper {
      tocItemMarkup = \tocItemWithDotsMarkup
    }

    \book {
      \markuplist \table-of-contents
      \tocItem \markup { Allegro }
      \tocItem \markup { Largo }
      \markup \null
    }

In addition to the built-in outline mechanism, custom commands can also be defined to build a more personalized table of contents with different markups In the following example, a new style is defined for entering act and scenes in the table of contents of an opera:

A new markup variable (called `tocActMarkup`) is defined in the `\paper` block:

    \paper {
      tocActMarkup = \markup \large \column {
        \hspace #1
        \fill-line { \null \italic \fromproperty #'toc:text \null }
        \hspace #1
      }
    }

A custom music function (`tocAct`) is then created – which uses the new `tocActMarkup` markup definition, and allows to specify a label for each act.

    tocAct =
      #(define-music-function (label text) (symbol? markup?)
         (add-toc-item! 'tocActMarkup label text))

Using these custom definitions and modifying some of the existing definitions, the source file could then be written as follows:

The previous example also demonstrates how to use the `\fill-with-pattern` markup command within the context of a table of contents.

#### See also

Installed Files: ‘`ly/toc-init.ly`’.

#### Predefined commands

`\table-of-contents`, `\tocItem`, `tocItemMarkup`, `tocTitleMarkup`, `tocFormatMarkup`, `tocIndentMarkup`.

#### LilyPond — Notation Reference v2.22.2 (stable-branch).