Table of Contents Positioning
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.
In this case, the sidebar column containing the TOC is both fixed and scrollable.
= The Dangerous and Thrilling Documentation Chronicles Kismet Chameleon :toc: left This journey begins on a bleary... == Cavern Glow The river rages through the cavern, rattling its content... == The Ravages of Writing Her finger socks had been vaporized by crystalline nuggets of... === A Recipe for Potion Two fresh Burdockian leaves, harvested by the light of the teal moons...
This positioning is achieved using CSS, which means it depends on support from the stylesheet. However, it’s only honored if there’s sufficient room on the screen for a sidebar column. If there isn’t sufficient room available (i.e., the screen width falls below a certain breakpoint), the TOC will automatically shift 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 values of
auto (the default),
macro place the TOC in the main document area.
When the value of
toc attribute is unspecified or
auto, the TOC is inserted directly below the document header (document title, author and revision lines).
toc is set to
preamble, the TOC is placed immediately below the preamble.
When using the preamble placement, the TOC will not appear if your document does not have a preamble.
To fix this problem, just set the
To place the TOC anywhere else in the document, set the
toc attribute to
Then, put the block toc macro (
toc::) at the location in the document where you want the TOC to appear.
The toc macro should appear at most once in any document.
toc is not set to
macro, any toc macro in the document will be silently ignored.
= The Dangerous and Thrilling Documentation Chronicles Kismet Chameleon :toc: macro (1) This journey begins on a bleary... == Cavern Glow toc:: (2) The river rages through the cavern, rattling its content...
|1||The toc attribute must be set to
|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.|
When AsciiDoc is converted to embeddable HTML (i.e., the
header_footer option is
false), there are only three valid values for the
auto (or unspecified value)
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.|