默认情况下，当`toc`属性被设置且其值留空或设置为`auto`时，目录会直接插入到文档标题、作者和修订行下方。通过为`toc`属性分配内置的位置值之一可以改变这个位置。这些值有：

  • 左

  • 右边

  • 序文

  • 宏

  • auto`（默认）

将目录显示为侧栏

在转换为HTML时，您可以通过分别为`toc`属性分配`left`或`right`值，将目录定位在主内容列的左侧或右侧。包含目录的边栏列既是固定的又是可滚动的。

将左边的值赋给toc
Unresolved directive in position.adoc - include::example$toc.adoc[tag=header]
:toc: left
Unresolved directive in position.adoc - include::example$toc.adoc[tag=body]

结果显示在下面。

将目录显示为侧边栏

这种定位是通过使用CSS来实现的，并且依赖于样式表的支持。

Warning
 侧边位置（左侧和右侧）有宽度要求。只有当屏幕上有足够的空间来适应侧边栏列（通常至少为768px）时，这些位置才被考虑。如果没有足够的空间（即屏幕宽度低于断点），目录*自动回到中间*，直接出现在文档标题下方。
Note
 在可嵌入的HTML文档中，目录(TOC)始终居中放置，不管`toc`属性的值是什么。

在前言下显示目录

当`toc`被赋予内置值`preamble`时，目录会被放置在前言的正下方。

将前导码的值赋给toc
Unresolved directive in position.adoc - include::example$toc.adoc[tags=header;preamble]

将前导码的值赋给toc的结果如下所示。

在序言下方显示目录
Caution
 当使用`preamble`值时，如果您的文档没有前言部分，目录将不会显示。要解决这个问题，将`toc`属性设置为空值（即，不填写任何值）或将其赋值为`auto`。

使用TOC宏来定位目录

要在文档中的特定位置放置目录(TOC)，将`macro`值分配给`toc`属性。然后，在你希望目录出现的文档中的行上输入目录块宏（即，TOC宏）。在文档中，TOC宏应该只使用一次。

如果`toc`文档属性没有被赋值为`macro`，文档中的任何TOC宏将被忽略。

将宏的值分配给toc
Unresolved directive in position.adoc - include::example$toc.adoc[tags=header;macro]

  1. 要启用TOC宏的使用，toc 属性必须设置为 macro。

  2. 在这个例子中，TOC宏放置在第一个部分的标题下方，表示一旦文档被渲染，目录将会显示在这个位置。

将宏的值分配给toc的结果显示如下。

使用TOC宏显示目录。

可嵌入的HTML，编辑器和预览器限制

当AsciiDoc转换为可嵌入的HTML（即，`header_footer`选项为`false`时），`toc`属性仅有三个有效值：

  • 自动/auto

  • 序文

  • 宏

以下所有环境都将AsciiDoc转换为可嵌入的HTML：

  • GitHub和GitLab上的文件查看器

  • 在Atom、Brackets或AsciidocFX等编辑器中预览AsciiDoc文档。

  • Asciidoctor浏览器扩展

Important
 在这种模式下，侧栏位置（左侧或右侧）是不可用的。这是因为嵌入式 HTML 缺少支持侧栏目录所需的外部框架（或 CSS）。