Docinfo Files

Docinfo is a feature of AsciiDoc that allows you to insert custom content into the head, header, or footer of the output document. This custom content is read from files known as docinfo files by the converter. Docinfo files are intended as convenient way to supplement the output produced by a converter. Examples include injecting auxiliary metadata, stylesheets, and scripting logic not already provided 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 are consumed 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 recommended as it’s already emitted by the converter.

You do not need to include the enclosing <head> element 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.

You can find a real-world example of a docinfo file for DocBook in the source of the Clojure Cookbook.

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

One possible use of the header docinfo file is to completely replace the default header in the standard stylesheet. Just set the attribute noheader, then apply a custom header 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>`
	Header	Adds content to start of document for <docname>.adoc files.	`<docname>-docinfo-header<outfilesuffix>`
	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>`
	Header	Adds content to start of document for any document in same directory.	`docinfo-header<outfilesuffix>`
	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-header
private-footer
private (alias for private-head,private-header,private-footer)
shared-head
shared-header
shared-footer
shared (alias for shared-head,shared-header,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, header and footer files, if they exist, as well as the private footer file, if it exists.

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 directory as the document file (which can be overridden by setting the :base_dir API option / --base-dir CLI option). If you want to load them from another location, set the docinfodir attribute to the directory where the files are located. If the value of the docinfodir attribute is a relative path, that value is appended to the document directory. If the value is an absolute path, that value is used as is.

:docinfodir: common/meta

Note that if you use this attribute, only the specified folder will be searched; docinfo files in the document directory 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 (docinfo.xml) 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: shared

Then the converted DocBook output would be:

Example 5. Converted DocBook containing the docinfo

<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml: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>
<date>2020-12-30</date>
<authorinitials>AN</authorinitials>
</revision>
</revhistory>
<edition>1.0</edition> (1)
</info>
</book>

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

Another example is if you want to define the license link tag in the HTML head.

Example 6. Docinfo file (docinfo.html) containing a license meta tag

<link rel="license" href="{license-url}" title="{license-title}">

Now define these attributes in your AsciiDoc source:

Example 7. Source document that defines license attributes

= Document Title
:license-url: https://mit-license.org
:license-title: MIT
:docinfo: shared

Then the <head> tag in the converted HTML would include:

Example 8. Rendered license link tag in HTML output

<link rel="license" href="https://mit-license.org" title="MIT">