章节将文档划分成一个内容层次结构。一个章节是一个隐式封闭体。每个章节以标题开始,并在下一个同级章节、上级章节或文档末尾结束。嵌套的章节级别必须是连续的。
章节级别语法
章节标题标志着一个章节的开始,同时也充当该章节的标题。章节标题必须有一个章节标记作为前缀,该标记表示章节的层次。标记中等号的数量代表基于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]
章节层次必须按逻辑嵌套。你必须遵循两条规则:
-
一个文档如果将`doctype`设置为`book`,那么它才能拥有多个0级别的部分。
-
第一个0级段落是文档标题;后续的0级段落代表不同部分。
-
-
在嵌套节时,不能跳过节的级别(例如,不能直接在三级节内嵌套一个五级节;需要一个中间的四级节)。
例如,以下语法是非法的:
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>`元素。