= Table of Contents
:navtitle: TOC

== Add a TOC

The table of contents (TOC) is not included by default.
The TOC is only included if the `toc` attribute is set on the document.

[,asciidoc]
----
= Document Title
:doctype: book
:toc: <.>

== Chapter A

== Chapter B
----
<.> Set the `toc` attribute in the document header.

The value assigned to `toc` determines the placement of the TOC.
If a value isn't specified, like in the above example, the placement defaults to `auto`, which is directly after the document title.
For documents that have the `book` doctype, the TOC is inserted using discrete pages between the title page and the first page of content.
This same behavior is used for all other doctypes if the `title-page` attribute is set and the value of the `toc-break-after` theme key is not `auto`.
Except for the aforementioned cases, the TOC is inserted in the flow of text.
If a placement is not specified, that location is between the document title and the first block of content.

While the table of contents isn't generated by default, the PDF outline is included unless xref:pdf-outline.adoc#deactivate[explicitly deactivated].
The `toclevels` attribute controls the depth of both the TOC and the PDF outline, regardless of whether the TOC is enabled.
The depth of the PDF outline can be controlled independently using the xref:pdf-outline.adoc#levels[outlinelevels attribute].
Both the `toclevels` and `outlinelevels` attributes can be set as a block attribute on each section to override the respective depth of the TOC or outline for that section.

== TOC depth

You can adjust the depth of section levels displayed in the TOC using the `toclevels` document attribute.

[,asciidoc]
----
= Document Title
:toclevels: 3 <.>
----
<.> Set the `toclevels` document attribute in the document header.

Accepted values for the `toclevels` document attribute are 1 through 5, as well as 0 for multipart books.

You can override the `toclevels` document attribute for a specific section and its children by setting the `toclevels` block attribute on the respective section.

[,asciidoc]
----
= Document Title
:toclevels: 1

== Section title

Content.

[toclevels=2] <.>
== Section title

Content.

=== Section title
----
<.> Temporarily overrides the `toclevels` document attribute with the value `2` until the next sibling section.

The block attribute temporarily changes the value of the document attribute and thus refers to the absolute depth.
Therefore, it must take into account the depth of the section on which it is set.

== Remove section from TOC

You can exclude a section (and all its descendants) from the TOC by setting the `toclevels` block attribute on the section to a value less than itself.
In this case, the section excludes itself.
When set on a section is the only time the toclevels value can only be less than the level of the top-level sections in the document.
For example:

[,asciidoc]
----
= Document Title
:toc:

[dedication,toclevels=0]
== Dedication

The dedication will not be included in the TOC.

== First Section in TOC

...
----

If you only want to exclude the descendants of a section from the TOC, you can set the `toclevels` block attribute to the level of the section.
In this case, the section excludes its own descendants, but not itself.
For example:

[,asciidoc]
----
= Document Title
:toc:
:toclevels: 3

[toclevels=1]
= Section Title

== Subsection Title

This subsection will not be included in the TOC.

...
----

Thus, by using the `toclevels` block attributes on sections, you can pick and choose which sections get excluded from the TOC.
However, you cannot include a section in the TOC once its parent has already been excluded.

== Insert TOC entries

You can add TOC entries for a preface, preamble, or imported PDF pages using the `notitle` option.
See xref:notitle.adoc[] for more information and examples.
You can also add a TOC entry for a preface using the method described in the <<preface,next section>>.

[#preface]
=== Preface TOC entry

The preface section in a `book` doctype doesn't get a TOC entry by default.
You have to set the `preface-title` document attribute and assign it a value.

[,asciidoc]
----
= Document Title
:doctype: book <.>
:preface-title: Preface <.>
:toc:

== Preface <.>

This is the preface.

== Chapter A

== Chapter B
----
<.> The doctype must be `book`.
<.> Set the `preface-title` document attribute and assign it the title you want displayed as the preface section title and in the TOC.
<.> Create a preface section.

Alternatively, if you want to hide the preface section title in the document body, but still want an entry for it in the TOC, apply the `notitle` option to the preface section title.
See xref:notitle.adoc#preface[Add a preamble or anonymous preface to the TOC] for examples and more information.

== TOC styling

You can customize the arrangement and style of the TOC, its title, heading levels, and dot leader by extending the theme and using the xref:theme:toc.adoc[].
