章节将文档划分成一个内容层次结构。一个章节是一个隐式封闭体。每个章节以标题开始,并在下一个同级章节、上级章节或文档末尾结束。嵌套的章节级别必须是连续的。

章节级别语法

章节标题标志着一个章节的开始,同时也充当该章节的标题。章节标题必须有一个章节标记作为前缀,该标记表示章节的层次。标记中等号的数量代表基于0的索引层次(例如,两个等号表示1级层次)。章节标记可以从两个等号到六个等号,并且必须后接一个空格。

在HTML输出中,章节标题由标题标签表示。标题标签的数量比章节级别多一(例如,一级章节变成h2标签)。章节级别的范围是0-5。这个限制主要是因为HTML只提供从h1到h6的标题标签(使得5级成为最高限制)。

文章文档类型中可用的章节标题
Unresolved directive in titles-and-levels.adoc - include::example$section.adoc[tag=base]

章节标题呈现为:

Unresolved directive in titles-and-levels.adoc - include::example$section.adoc[tag=b-base]

章节层次必须按逻辑嵌套。你必须遵循两条规则:

  1. 一个文档如果将`doctype`设置为`book`,那么它才能拥有多个0级别的部分。

    • 第一个0级段落是文档标题;后续的0级段落代表不同部分。

  2. 在嵌套节时,不能跳过节的级别(例如,不能直接在三级节内嵌套一个五级节;需要一个中间的四级节)。

例如,以下语法是非法的:

Unresolved directive in titles-and-levels.adoc - include::example$section.adoc[tag=bad]

位于第一个章节标题上方的内容被确定为文档的序言。一旦到达第一个章节标题,内容就与其所嵌套的章节相关联。

Unresolved directive in titles-and-levels.adoc - include::example$section.adoc[tag=content]
Tip
除了用于定义章节标题的等号标记外,Asciidoctor还识别Markdown中的井号(#)。这意味着Markdown文档的大纲结构可以很好地转换为AsciiDoc文档。

标题作为HTML标题

当文档被转换为HTML 5(使用内置的`html5`后端时),每个章节标题都会变成一个与等号数量相对应的标题元素。例如,一个一级章节(==)会对应一个`<h2>`元素。