文档信息文件

Docinfo是AsciiDoc的一个功能，它允许您将自定义内容插入到输出文档的头部、页眉或页脚中。这些自定义内容是由转换器从称为docinfo文件的文件中读取的。Docinfo文件旨在作为一种方便的方式来补充转换器产生的输出。示例包括注入辅助元数据、样式表以及转换器尚未提供的脚本逻辑。

docinfo功能并不适用于所有的后端。虽然它在转换为HTML和DocBook等输出格式时有效，但在使用Asciidoctor PDF转换为PDF时不起作用。

必须使用`docinfo`属性显式启用docinfo功能（参见启用文档信息）。消费哪些docinfo文件取决于`docinfo`属性的值以及后端。

头部文档信息文件

head docinfo文件的内容会被注入到文档的顶部。对于HTML，这些内容将被添加到`<head>`元素中。对于DocBook，内容会被添加到根`<info>`元素中。

HTML输出的docinfo文件可能包含有效的元素来填充HTML <head> 元素，包括：

<base>
<link>
<meta>
<noscript>
<script>
<style>

Caution

不建议使用`<title>`元素，因为转换器已经生成了它。

你不需要包含封闭的 <head> 元素，因为它被假定为信封。

这里有一个例子：

用于HTML输出的头部文档信息文件

<meta name="keywords" content="open source, documentation">
<meta name="description" content="The dangerous and thrilling adventures of an open source documentation team.">
<link rel="stylesheet" href="basejump.css">
<script src="map.js"></script>

HTML输出的Docinfo文件必须使用`.html`文件扩展名保存。有关更多详细信息，请参见命名文档信息文件。

DocBook 5.0 输出的 docinfo 文件可能包括https://tdg.docbook.org/tdg/5.0/info.html[<info> 元素的子项^]，例如：

<address>
<copyright>
<edition>
<keywordset>
<publisher>
<subtitle>
<revhistory>

以下示例展示了一个DocBook文档信息文件可能包含的一些内容。

用于DocBook 5.0输出的文档信息文件

<author>
  <personname>
    <firstname>Karma</firstname>
    <surname>Chameleon</surname>
  </personname>
  <affiliation>
    <jobtitle>Word SWAT Team Leader</jobtitle>
  </affiliation>
</author>

<keywordset>
  <keyword>open source</keyword>
  <keyword>documentation</keyword>
  <keyword>adventure</keyword>
</keywordset>

<printhistory>
  <para>April, 2021. Twenty-sixth printing.</para>
</printhistory>

DocBook输出的Docinfo文件必须以`.xml`文件扩展名保存。有关更多详细信息，请参阅命名文档信息文件。

你可以在https://github.com/clojure-cookbook/clojure-cookbook/blob/master/book-docinfo.xml[Clojure Cookbook^]的源码中找到一个DocBook的docinfo文件的真实世界例子。

Header docinfo文件通过在文件名中增加`-header`来与head docinfo文件区分开来。在HTML输出中，头部内容被立即插入到头部div之前（即`<div id="header">`）。在DocBook输出中，头部内容被插入到开头标签之后（例如，<article>`或<book>`）。

Tip	头文件docinfo文件的一个可能用途是完全替换标准样式表中的默认页眉。只需设置属性`noheader`，然后应用自定义的页眉docinfo文件。

页脚docinfo文件与页眉docinfo文件的区别在于文件名中增加了`-footer`。在HTML输出中，页脚内容紧跟在页脚div（即，<div id="footer">）之后插入。在DocBook输出中，页脚内容紧接在结束标签（例如，</article>`或</book>`）之前插入。

Tip	脚注docinfo文件的一个可能用途是完全替换标准样式表中的默认页脚。只需设置`nofooter`属性，然后应用一个自定义的页脚docinfo文件。

命名文档信息文件

用于提供docinfo的文件选择取决于正在使用哪种转换器（如html、docbook等）以及docinfo的应用范围是配置为特定文档（“private”）还是同一目录下所有文档（“shared”）。docinfo文件的文件扩展名必须与输出文件的文件扩展名相匹配（由`outfilesuffix`属性指定，该值始终以句点(.)开头）。

Table 1. Docinfo文件命名
模式	位置	行为	Docinfo文件名
私有	头部	为 `<docname>.adoc` 文件的 `<head>`/`<info>` 添加内容。	`<docname>-docinfo<outfilesuffix>`
	头信息	为 `<docname>.adoc` 文件开始处添加内容。	`<docname>-docinfo-header<outfilesuffix>`
	脚信息	为 `<docname>.adoc` 文件末尾添加内容。	`<docname>-docinfo-footer<outfilesuffix>`
共享	头部	为同一目录下任何文档的 `<head>`/`<info>` 添加内容。	`docinfo<outfilesuffix>`
	头信息	为同一目录下任何文档的开始处添加内容。	`docinfo-header<outfilesuffix>`
	脚信息	为同一目录下任何文档的末尾添加内容。	`docinfo-footer<outfilesuffix>

启用文档信息

要指定您要应用的文件，请将 docinfo 属性设置为以下值的任意组合：

private-head
private-header
private-footer
private`（别名为`private-head,private-header,private-footer`）
共享头
shared-header
shared-footer
"`shared`（`shared-head,shared-header,shared-footer`的别称）"

将 docinfo 设置为没有值等同于将值设置为 private。

例如：

:docinfo: shared,private-footer

如果存在共享的docinfo头文件、头部和页脚文件，以及私有的页脚文件（如果存在的话），这个docinfo配置将会应用它们。

让我们将这个应用到一个例子上：

您有两个AsciiDoc文档，adventure.adoc_和[.path]_insurance.adoc，保存在同一个文件夹中。您希望在它们转换为HTML时，在这两份文档的头部添加相同的内容。

创建一个包含 <head> 元素的 docinfo 文件。
将其保存为docinfo.html。
在 adventure.adoc 和 insurance.adoc 中设置 docinfo 属性为 shared。

你还想在[.path]_adventure.adoc_的开头包含一些附加内容。

创建一个包含`<head>`元素的*另一个* docinfo文件。
将其保存为[path]_adventure-docinfo.html。
将`.adoc`文件中的`docinfo`属性设置为`shared,private-head

如果将其他的AsciiDoc文件添加到同一文件夹中，并且在这些文件中将`docinfo`设置为`shared`，那么在转换那些文件时，只有[.path]docinfo.html 文件会被添加。

定位docinfo文件

默认情况下，docinfo文件在与文档文件相同的目录中进行搜索（可以通过设置API选项`--base-dir`或者命令行选项`--base-dir`来覆盖）。如果你希望将它们从其他位置加载，请将`docinfodir`属性设置为存放这些文件的目录。如果`docinfodir`属性的值是相对路径，则该值将附加到文档目录后面。如果该值是一个绝对路径，则将按原样使用该值。

:docinfodir: common/meta

请注意，如果您使用这个属性，那么只会搜索指定的文件夹；文档目录中的docinfo文件将不再被找到。