局部文件

可重用的单一来源内容

局部文件适用于存储内容片段,例如常见描述、项目介绍、术语、频繁的警告和参考表,在整个站点中您可以在一个或多个页面中重复使用这些内容。您对局部文件所做的更改将在下次构建站点时传播到引用了局部文件的所有页面。

局部文件名和文件扩展名

局部文件存储在一个partials目录中。局部文件通常使用AsciiDoc标记,并以.adoc文件扩展名保存。然而,局部文件不一定要是AsciiDoc文件,并且与可发布资源不同,没有文件扩展名的局部文件不会被视为隐藏文件。Antora将加载没有文件扩展名的局部文件到其内容目录中,并为局部文件分配一个资源ID以供引用。

保存新的局部文件时,请牢记以下文件名要求和建议:

  • 局部文件的文件名不能包含空格,因为AsciiDoc包含指令不接受带有空格的值。

  • 不建议在文件名中使用大写字母。某些文件系统不区分大小写。因此,根据作者使用的文件系统,可能会发生文件冲突。

  • 当局部文件是AsciiDoc文件时,请使用.adoc扩展名保存文件,否则请使用该文件类型的有效文件扩展名。仅当特定文件类型的惯例是不使用扩展名时,才保存不带文件扩展名的局部文件。保存局部文件时不使用正确的文件扩展名可能会限制您应用某些Antora扩展或升级到未来功能的能力。

Antora不会将局部文件作为单独的站点页面发布。局部文件必须通过包含指令从页面或最终包含在页面中的资源引用才能发布局部文件的内容。

创建局部文件

局部文件通常是使用AsciiDoc标记的常规内容。与页面不同,局部文件没有任何必需的结构元素,例如标题,尽管它可以包含这些元素。在下一节中,您将看到如何创建一个新的局部文件并使用AsciiDoc标记它。

设置AsciiDoc局部文件

  1. 在您的集成开发环境或纯文本编辑器中打开一个新文件。

  2. 在文件的第一行输入您的内容,例如段落文本、表格或属性条目。在这个示例中,让我们创建一个警告,该警告将在整个站点的多个页面中使用。

    [WARNING]
    ====
    高处的开阔地带在树线以上令人敬畏 -
    但您需要为海拔和迅速变化的天气条件做好准备。
    ====
  3. 完成内容创建后,将文件保存为.adoc扩展名,并保存在partials目录中。

    📂 modules
      📂 ROOT
        📂 pages
          📄 a-source-file.adoc
        📂 partials
          📄 treeline-warning.adoc

您已经创建了一个局部文件!现在,它已准备好被包含在一个页面中。无论局部文件属于哪个组件版本,都可以通过局部文件的资源ID和AsciiDoc包含指令被站点中的任何页面或局部引用。您甚至可以选择局部文件的区域或行,而不是全部内容,并使用包含指令的tagtagslines属性仅插入那些区域或行。

当前页面上下文和结构

在创建局部文件的内容时,有一些AsciiDoc元素可能需要根据当前页面的上下文和结构进行调整。局部文件在插入到页面后进行转换。因此,当前页面的组件版本、模块、属性和其他元素将被应用并可能影响包含的内容。

引用页面和资源

交叉引用

如果局部文件包含在属于其他模块或文档组件的页面中,则需要根据情况在局部文件的内容中指定目标页面或附件的资源ID。所需的资源ID坐标数量取决于当前页面的组件版本和模块,以及局部文件被插入的当前页面与局部文件内容中引用的目标附件或页面之间的关系。

图像、示例和其他局部文件

局部文件可以使用包含指令引用其他局部文件和示例,使用图像宏引用图像。与在交叉引用中输入资源ID类似,根据局部文件被包含的当前页面的组件版本和模块以及局部文件中引用的资源,可能需要指定目标资源的额外坐标。

章节标题

局部文件可以包含章节标题。根据在当前页面中输入引用包含指令的位置,您可能需要使用leveloffset属性调整局部文件的标题级别。

内联、块和章节ID

局部文件中的元素ID不能与插入的页面的元素ID发生冲突。

属性

可以在局部文件中设置、分配和引用属性。当在局部文件中引用属性时,局部文件、当前页面或当前页面的组件版本描述符必须设置和分配属性的值。

如果在局部文件中设置并分配了属性的值,则该属性将从包含局部文件的点开始在当前页面中可用。在这种情况下,局部文件的属性将覆盖当前页面标题中设置或未设置的同名属性,或从当前页面的组件版本描述符中软设置或取消设置的属性。