Docinfo

You can add custom content to the head, header, or footer of the 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.

In addition, you can add running content to the output document. Running content can then be positioned via CSS on the top, bottom, left or right margins of pages. This can come in handy when you want to repeat complex elements (address, contact…​) on all pages for documents like invoices or reports. If you want to learn more about running elements, see Running Elements.

You will need to declare running elements as running content via CSS. Otherwise, running elements will be visible on the page.

To enable docinfo files, you need to configure the scope using the docinfo attribute. The scope defines whether the docinfo files apply to a specific document ("private") or to all documents in the same directory ("shared").

Mode Location Behavior Docinfo file name

Private

Head

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

<docname>-docinfo-pdf.html

Private

Header

Adds content to the start of the document for <docname>.adoc files.

<docname>-docinfo-header-pdf.html

Private

Footer

Adds content to the end of the document for <docname>.adoc files.

<docname>-docinfo-footer-pdf.html

Private

Running

Adds running content to the start of the document for <docname>.adoc files.

<docname>-docinfo-running-pdf.html

Shared

Head

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

docinfo-pdf.html

Shared

Header

Adds content to the start of the document for any document in the same directory.

docinfo-header-pdf.html

Shared

Footer

Adds content to the end of the document for any document in the same directory.

docinfo-footer-pdf.html

Shared

Running

Adds running content to the start of the document for any document in the same directory.

docinfo-running-pdf.html

The generated HTML page contains no client-side JavaScript — Vivliostyle Viewer runs as a separate app and paginates the document without executing scripts embedded in it. If a docinfo footer file injects a <script> that needs to finish running (e.g., to render a chart) before the document is converted, use the --preprocess-scripts (or --preprocess-scripts-wait-for) CLI option so the script runs and completes before the PDF is generated.

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

  • private (alias for private-head,private-header,private-footer,private-running)

  • shared-head

  • shared-header

  • shared-footer

  • shared-running

  • shared (alias for shared-head,shared-header,shared-footer,shared-running)

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

For example:

:docinfo: shared,private-footer

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