Docinfo Files

You can add custom content to the head or footer of an output document using docinfo files. Docinfo files are useful for injecting auxiliary metadata, stylesheet, and script information into the output not added by the converter.

The docinfo feature does not apply to all backends. While it works when converting to output formats such as HTML and DocBook, it does not work when converting to PDF using Asciidoctor PDF.

The docinfo feature must be explicitly enabled using the docinfo attribute (see Enabling docinfo). Which docinfo files get used depends on the value of the docinfo attribute as well as the backend.

Head docinfo files

The content of head docinfo files gets injected into the top of the document. For HTML, the content is append to the <head> element. For DocBook, the content is appended to the root <info> element.

The docinfo file for HTML output may contain valid elements to populate the HTML <head> element, including:

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

Use of the <title> element is not recommend as it’s already emitted by the converter.

You do not need to include the enclosing <head> tag as it’s assumed to be the envelope.

Here’s an example:

Example 1. A head docinfo file for HTML output

<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>

Docinfo files for HTML output must be saved with the .html file extension. See Naming docinfo files for more details.

The docinfo file for DocBook 5.0 output may include any of the <info> element’s children, such as:

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

The following example shows some of the content a docinfo file for DocBook might contain.

Example 2. A docinfo file for DocBook 5.0 output

<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>

Docinfo files for DocBook output must be saved with the .xml file extension. See Naming docinfo files for more details.

To see a real-world example of a docinfo file for DocBook, checkout the RichFaces Developer Guide docinfo file.

Footer docinfo files are differentiated from head docinfo files by the addition of -footer to the file name. In the HTML output, the footer content is inserted immediately after the footer div (i.e., <div id="footer">). In the DocBook output, the footer content is inserted immediately before the ending tag (e.g., </article> or </book>).

One possible use of the footer docinfo file is to completely replace the default footer in the standard stylesheet. Just set the attribute nofooter, then apply a custom footer docinfo file.

Naming docinfo files

The file that gets selected to provide the docinfo depends on which converter is in use (html, docbook, etc) and whether the docinfo scope is configured for a specific document (“private”) or for all documents in the same directory (“shared”). The file extension of the docinfo file must match the file extension of the output file (as specified by the outfilesuffix attribute, a value which always begins with a period (.)).

Docinfo file naming
Mode	Location	Behavior	Docinfo file name
Private	Head	Adds content to `<head>`/`<info>` for <docname>.adoc files.	`<docname>-docinfo<outfilesuffix>`
Private	Footer	Adds content to end of document for <docname>.adoc files.	`<docname>-docinfo-footer<outfilesuffix>`
Shared	Head	Adds content to `<head>`/`<info>` for any document in same directory.	`docinfo<outfilesuffix>`
Shared	Footer	Adds content to end of document for any document in same directory.	`docinfo-footer<outfilesuffix>`

Enabling docinfo

To specify which file(s) you want to apply, set the docinfo attribute to any combination of these values:

private-head
private-footer
private (alias for private-head,private-footer)
shared-head
shared-footer
shared (alias for shared-head,shared-footer)

Setting docinfo with no value is equivalent to setting the value to private.

For example:

:docinfo: shared,private-footer

This docinfo configuration will apply the shared docinfo head and footer files, if they exist, as well as the private footer file, if it exists.

docinfo attribute values were introduced in Asciidoctor 1.5.5 to replace the less descriptive docinfo1 and docinfo2 attributes. Here are the equivalents of the old attributes using the new values:

:docinfo: = :docinfo: private
:docinfo1: = :docinfo: shared
:docinfo2: = :docinfo: shared,private

Let’s apply this to an example:

You have two AsciiDoc documents, adventure.adoc and insurance.adoc, saved in the same folder. You want to add the same content to the head of both documents when they’re converted to HTML.

Create a docinfo file containing <head> elements.
Save it as docinfo.html.
Set the docinfo attribute in adventure.adoc and insurance.adoc to shared.

You also want to include some additional content, but only to the head of adventure.adoc.

Create another docinfo file containing <head> elements.
Save it as adventure-docinfo.html.
Set the docinfo attribute in adventure.adoc to shared,private-head

If other AsciiDoc files are added to the same folder, and docinfo is set to shared in those files, only the docinfo.html file will be added when converting those files.

Locating docinfo files

By default, docinfo files are searched for in the same folder as the document file. If you want to keep them anywhere else, set the docinfodir attribute to their location:

:docinfodir: common/meta

Note that if you use this attribute, only the specified folder will be searched; docinfo files in the document folder will no longer be found.

Attribute substitution in docinfo files

Docinfo files may include attribute references. Which substitutions get applied is controlled by the docinfosubs attribute, which takes a comma-separated list of substitution names. The value of this attribute defaults to attributes.

For example, if you created the following docinfo file:

Example 3. Docinfo file containing a revnumber attribute reference

<edition>{revnumber}</edition>

And this source document:

Example 4. Source document including a revision number

= Document Title
Author Name
v1.0, 2020-12-30
:doctype: book
:backend: docbook
:docinfo:

Then the converted DocBook output would be:

<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook"
    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" lang="en">
  <info>
    <title>Document Title</title>
    <date>2020-12-30</date>
    <author>
      <personname>
        <firstname>Author</firstname>
        <surname>Name</surname>
      </personname>
    </author>
    <authorinitials>AN</authorinitials>
    <revhistory>
      <revision>
        <revnumber>1.0</revnumber> (1)
        <date>2020-12-30</date>
        <authorinitials>AN</authorinitials>
      </revision>
    </revhistory>
  </info>
</book>

1	The revnumber attribute reference was replaced by the source document’s revision number in the converted output.