Position the TOC
By default, the table of contents is inserted directly below the document title, author, and revision lines when the
toc attribute is set and its value is left empty or set to
This location can be changed by assigning one of the built-in positional values to the
The values are:
When converting to HTML, you can position the TOC to the left or right of the main content column by assigning the value
right to the
toc attribute, respectively.
The sidebar column containing the TOC is both fixed and scrollable.
= The Intrepid Chronicles Kismet Lee; B. Steppenwolf; Pax Draeke :toc: left == Certain Peril Daylight trickles across the cobblestones... === A Recipe for Potion We have to harvest the leaves by the light of the teal moons... ==== Searching for Ginseng Crawling through the twisted understory... == Dawn on the Plateau Hanging from...
The result of Example 1 is displayed below.
This positioning is achieved using CSS and depends on support from the stylesheet.
|The side positions (left and right) have a width requirement. These positions are only honored if there’s sufficient room on the screen to fit the sidebar column (typically at least 768px). If sufficient room available is not available (i.e., the screen width falls below the breakpoint), the TOC automatically shifts back to the center, appearing directly below the document title.|
The TOC is always placed in the center in an embeddable HTML document, regardless of the value of the
toc is assigned the built-in value
preamble, the TOC is placed immediately below the preamble.
= The Intrepid Chronicles Kismet Lee; B. Steppenwolf; Pax Draeke :toc: preamble This adventure begins on a frigid morning. We've run out of coffee beans, but leaving our office means venturing into certain peril. == Certain Peril Daylight trickles across the cobblestones... == Dawn on the Plateau Hanging from...
The result of Example 2 is displayed below.
When using the
To place the TOC in specific location in the document, assign the
macro value to the
Then, enter the table of contents block macro (i.e., TOC macro) on the line in your document where you want the TOC to appear.
The TOC macro should only be used once in a document.
toc document attribute isn’t assigned the value
macro, any TOC macro in the document will be ignored.
= The Intrepid Chronicles Kismet Lee; B. Steppenwolf; Pax Draeke :toc: macro (1) == Certain Peril toc:: (2) Daylight trickles across the cobblestones... == Dawn on the Plateau Hanging from...
|2||In this example, the TOC macro is placed below the first section’s title, indicating that this is the location where the TOC will be displayed once the document is rendered.|
The result of Example 3 is displayed below.
When AsciiDoc is converted to embeddable HTML (i.e., the
header_footer option is
false), there are only three valid values for the
All of the following environments convert AsciiDoc to embeddable HTML:
the file viewer on GitHub and GitLab
the AsciiDoc preview in an editor like Atom, Brackets or AsciidocFX
the Asciidoctor browser extensions
|The side column placement (left or right) isn’t available in this mode. That’s because the embeddable HTML doesn’t have the outer framing (or the CSS) necessary to support a side column TOC.|