文档结构

在这个页面上，你将了解到一个AsciiDoc文档的整体结构。目前不用担心语法的细节问题，这个话题将在文档的后面部分进行彻底讲解。现在，我们只是想要对构成一个AsciiDoc文档的内容有一个基本的认识。

文件

AsciiDoc是一种纯文本写作格式，没有固定的外壳或前言。一个AsciiDoc文档可能只包含一个句子（甚至从学术角度说是一个字符）。

以下示例是一个有效的AsciiDoc文档，包含一个包含单个句子的段落：

这是一个基础的AsciiDoc文档。

当然，你可以拥有比单个句子更多的内容。我们在这里想要强调的是，开始变得很简单。

一个AsciiDoc文档是一系列按行堆叠在一起的块。这些块通常通过空行相互之间保持偏移（尽管在某些情况下这些空行可能是可选的）。

要将前一个文档从一个段落扩展为两个段落，你需要用一个空行将这两个段落分开：

这是一个基础的AsciiDoc文档。

这个文档包含两个段落。

一个AsciiDoc文档可能以文档头部开始。虽然文档头部是可选的，但它经常被使用，因为它允许你指定文档标题，并且可以设置文档范围的配置和以文档属性的形式设置可复用的文本。

= 文档标题
可复现

这是一个由{author}创建的基本AsciiDoc文档。

这份文件包含两个段落。它还有一个头部，指定了文档标题。

几乎任何块的组合都构成一个有效的AsciiDoc文档（文档类型根据文档类型规定了一些结构性要求）。文档可以从单个句子扩展到多部分组成的书籍。

在AsciiDoc中，行是一个重要的结构。行被定义为被新行字符或文档边界分隔在两边的文本。许多语法特性必须占据整个行。这就是为什么我们说AsciiDoc是一种面向行的语言。

例如，章节标题必须单独成行。属性条目、区块标题、区块属性列表、区块宏命令、列表项、区块分隔符等也是如此。

段落标题的示例，必须占据一整行

== 章节标题

属性条目的示例，也必须至少占用一行

:name: value

一个属性条目的例子，它延伸到两行

:name: 值 \
更多的值

空行也可能很重要。一个单独的空行将头部和正文分开。正如你在之前的两段示例中看到的，许多块也是通过一个空行来分隔的。

相比之下，段落内容中的行是不重要的。在你学习AsciiDoc语法时请记住这些点。

AsciiDoc文档中的块构成了文档结构。一些块可能包含其他块，因此文档结构本质上是层级的（即，树状结构）。例如，通过启用自动生成的内容表，你可以预览这个部分的结构。块的示例包括段落、章节、列表、定界块、表格和块宏。

块很容易识别，因为它们通常会因为空行与其他块区分开来（尽管这并非总是必需的）。块总是开始于新的一行，在一行的结尾结束，并且与左边距对齐。

每个块可以有一个或多个块元数据行。这些元数据可以是块属性、块锚点或块标题的形式。这些元数据行必须位于块本身的上方且与块直接相邻。

节、非逐字传输的限定块，以及AsciiDoc表格单元格可以包含其他块。尽管块构成了层次结构，即使是嵌套块也要从左边距开始。通过要求块从左边距开始，它避免了跟踪和维护缩进级别的繁琐，并使内容更易于重用。

标记、定界符和元数据行环绕的是文本。文本是文档的主要焦点，这也是AsciiDoc语法给予它如此多的空间以自由表达的原因。文本最常见于块的行中（例如，段落）、块标题（例如，章节标题）以及列表项中，尽管还有其他地方文本也可能存在。

文本会受到替换。替换会将标记解释为文本格式化，用文本或非文本元素替换宏，扩展属性引用，并执行其他类型的文本替换。

普通文本会进行所有的替换，除非另有规定。直接文本只进行最少量的替换，以便它能在输出中按照源码中的样子显示。也可以禁用所有替换，以便原样（即，原始格式）传递文本到输出中。文本解析最终会是内联元素和其它形式转换的混合体。

AsciiDoc文件是一个文本文件，它具有_.adoc_文件扩展名（例如，document.adoc）。大多数AsciiDoc处理器假定文件中的文本使用UTF-8编码。只有文件以BOM开头时，才支持UTF-16编码。

AsciiDoc处理器可以处理来自字符串（即字符序列）的AsciiDoc。然而，大多数时候你会将你的AsciiDoc文档保存到一个文件中。