Partials

可重用的单一源内容

Partials 适合存储内容片段，如公共描述、项目介绍、术语、经常警告和参考表，这些内容可以在整个站点的一个或多个页面中重用。您对部分所做的更改将在下次构建站点时传播到您引用部分(partial)的所有页面。

部分文件名和文件扩展名

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

保存新的 partial 文件时，请记住以下文件名要求和建议：

部分文件名不能包含空格，因为 AsciiDoc include 指令不接受带空格的值。
文件名中不建议使用大写字母。有些文件系统不区分大小写。因此，根据写入器使用的文件系统不同，可能会发生文件冲突。
如果是 AsciiDoc 文件，则使用 .adoc 扩展名保存部分文件，否则使用文件类型的有效文件扩展名。您应该只保存没有文件扩展名的部分，因为行业惯例中特定的文件类型没有扩展名。在保存部分文件时不使用正确的文件扩展名可能会限制您应用某些 Antora 扩展名或升级到未来功能的能力。

Antora 不将部分(partial)文件作为单独的站点页面发布。为了发布分部(partial)的内容，分部(partial)的内容必须由页面或最终包含在页面中的资源中的 include 指令引用。

创建部分文件

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

设置一个 AsciiDoc 部分(aprtial)文件

在 IDE 或纯文本编辑器中打开一个新文件。
在文件的第一行，输入内容，如段落文本、表格或属性条目。在这个示例中，让我们创建一个将在整个站点的多个页面上使用的警告。
```
[WARNING]
====
High, open places above the treeline are awe-inspiring--
but you need to be prepared for the altitude and
rapidly changing weather conditions.
====
```

创建完内容后，将扩展名为 .adoc 的文件保存在 partials 目录中。

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

您已经创建了一个 partial! 现在，可以将它包含在页面中了。不管一个部分属于哪个组件版本，它都可以通过使用部分资源 ID 和 AsciiDoc include 指令被站点中的任何页面或部分引用。您甚至可以从部分内容中选择区域或行，而不是从所有部分内容中选择，并使用 include 指令的标记、标记或 lines 属性只插入那些区域或行。

当前页面上下文和结构

在部分(partial)中创建内容时，可能需要根据当前页面的上下文和结构对某些 AsciiDoc 元素进行调整。将部分插入页面后进行转换。因此，当前页面的组件版本、模块、属性和其他元素将应用于并可能影响所包含的内容。

引用页面和资源

Xrefs: 如果部分(partial)包含在属于其他模块或文档组件的页面中，则需要指定相应分配给部分内容中的 xref 宏的目标页面或附件的资源 ID 。所需资源 ID 坐标的数量取决于插入部分的当前页面的组件版本和模块，相对于部分内容中的目标附件或由 xref 宏引用的页面。
Images, examples, and other partials: 部分(partial)可以使用 include 指令引用其他局部和示例，使用 image 宏引用图像。就像在 xref 中输入资源 ID 一样，目标资源的资源 ID 可能需要根据当前页面的组件版本和模块来指定额外的坐标，当前页面中包含的部分以及部分中引用的资源。

章节头

部分可以包含节标题。您可能需要使用 leveloffset 属性来调整部分标题的级别，这取决于您在当前页面中输入引用 include 指令的位置。

内联，块和章节IDs

部分中的元素 ID 不能与插入它的页面的元素 ID 冲突。

属性

可以在局部中设置、分配和引用属性。当一个属性在分部中被引用时，分部、当前页或当前页的组件版本描述符必须为该属性设置并赋值。

如果在部分中设置了属性并为其赋值，则从包含部分的位置开始，该属性将在当前页面中可用。在这种情况下，部分的属性将覆盖在当前页面标头中设置或取消设置的同名属性，或者在当前页面组件版本描述符中设置或取消设置的同名属性。