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

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  element is not recommend 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.">
<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>
</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

Adds content to <head>/<info> for <docname>.adoc files.

<docname>-docinfo<outfilesuffix>

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

Adds content to <head>/<info> for any document in same directory.

docinfo<outfilesuffix>

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.

 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.

1. Create a docinfo file containing <head> elements.

2. Save it as docinfo.html.

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

1. Create another docinfo file containing <head> elements.

2. Save it as adventure-docinfo.html.

3. 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 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"
<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.