13.3 Table of Contents

The table of contents includes all headlines in the document. Its depth is therefore the same as the headline levels in the file. If you need to use a different depth, or turn it off entirely, set the org-export-with-toc variable accordingly. You can achieve the same on a per file basis, using the following ‘toc’ item in ‘OPTIONS’ keyword:

#+OPTIONS: toc:2          (only include two levels in TOC)
#+OPTIONS: toc:nil        (no default TOC at all)

Org includes both numbered and unnumbered headlines in the table of contents¹²⁵. If you need to exclude an unnumbered headline, along with all its children, set the ‘UNNUMBERED’ property to ‘notoc’ value.

* Subtree not numbered, not in table of contents either
  :PROPERTIES:
  :UNNUMBERED: notoc
  :END:

Org normally inserts the table of contents directly before the first headline of the file. To move the table of contents to a different location, first turn off the default with org-export-with-toc variable or with ‘#+OPTIONS: toc:nil’. Then insert ‘#+TOC: headlines N’ at the desired location(s).

#+OPTIONS: toc:nil
...
#+TOC: headlines 2

To adjust the table of contents depth for a specific section of the Org document, append an additional ‘local’ parameter. This parameter becomes a relative depth for the current level. The following example inserts a local table of contents, with direct children only.

* Section
#+TOC: headlines 1 local

Note that for this feature to work properly in LaTeX export, the Org file requires the inclusion of the titletoc package. Because of compatibility issues, titletoc has to be loaded before hyperref. Customize the org-latex-default-packages-alist variable.

The following example inserts a table of contents that links to the children of the specified target.

* Target
  :PROPERTIES:
  :CUSTOM_ID: TargetSection
  :END:
** Heading A
** Heading B
* Another section
#+TOC: headlines 1 :target #TargetSection

The ‘:target’ attribute is supported in HTML, Markdown, ODT, and ASCII export.

Use the ‘TOC’ keyword to generate list of tables—respectively, all listings—with captions.

#+TOC: listings
#+TOC: tables

Normally Org uses the headline for its entry in the table of contents. But with ‘ALT_TITLE’ property, a different entry can be specified for the table of contents.