Header

The Header contains document meta-data, typically title plus optional authorship and revision information:

  • The Header is optional, but if it is used it must start with a document title.
  • Optional Author and Revision information immediately follows the header title.
  • The document header must be separated from the remainder of the document by one or more blank lines and cannot contain blank lines.
  • The header can include comments.
  • The header can include attribute entries, typically doctype, lang, encoding, icons, data-uri, toc, numbered.
  • Header attributes are overridden by command-line attributes.
  • If the header contains non-UTF-8 characters then the encoding must precede the header (either in the document or on the command-line).

Here’s an example AsciiDoc document header:

Writing Documentation using AsciiDoc
====================================
Joe Bloggs <jbloggs@mymail.com>
v2.0, February 2003:
Rewritten for version 2 release.

The author information line contains the author’s name optionally followed by the author’s email address. The author’s name is formatted like:

firstname[ [middlename ]lastname][ <email>]]

i.e. a first name followed by optional middle and last names followed by an email address in that order. Multi-word first, middle and last names can be entered using the underscore as a word separator. The email address comes last and must be enclosed in angle <> brackets. Here a some examples of author information lines:

Joe Bloggs <jbloggs@mymail.com>
Joe Bloggs
Vincent Willem van_Gogh

If the author line does not match the above specification then the entire author line is treated as the first name.

The optional revision information line follows the author information line. The revision information can be one of two formats:

  1. An optional document revision number followed by an optional revision date followed by an optional revision remark:
    • If the revision number is specified it must be followed by a comma.
    • The revision number must contain at least one numeric character.
    • Any non-numeric characters preceding the first numeric character will be dropped.
    • If a revision remark is specified it must be preceded by a colon. The revision remark extends from the colon up to the next blank line, attribute entry or comment and is subject to normal text substitutions.
    • If a revision number or remark has been set but the revision date has not been set then the revision date is set to the value of the docdate attribute.

    Examples:

    v2.0, February 2003
February 2003
v2.0,
v2.0, February 2003: Rewritten for version 2 release.
February 2003: Rewritten for version 2 release.
v2.0,: Rewritten for version 2 release.
:Rewritten for version 2 release.

  2. The revision information line can also be an RCS/CVS/SVN $Id$ marker:
    • AsciiDoc extracts the revnumber, revdate, and author attributes from the $Id$ revision marker and displays them in the document header.
    • If an $Id$ revision marker is used the header author line can be omitted.

    Example:

    $Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $

You can override or set header parameters by passing revnumber, revremark, revdate, email, author, authorinitials, firstname and lastname attributes using the asciidoc(1) -a (--attribute) command-line option. For example:

$ asciidoc -a revdate=2004/07/27 article.txt

Attribute entries can also be added to the header for substitution in the header template with Attribute Entry elements.

The title element in HTML outputs is set to the AsciiDoc document title, you can set it to a different value by including a title attribute entry in the document header.

Additional document header information

AsciiDoc has two mechanisms for optionally including additional meta-data in the header of the output document:

docinfo configuration file sections
If a configuration file section named docinfo has been loaded then it will be included in the document header. Typically the docinfo section name will be prefixed with a + character so that it is appended to (rather than replace) other docinfo sections.
docinfo files
Two docinfo files are recognized: one named docinfo and a second named like the AsciiDoc source file with a -docinfo suffix. For example, if the source document is called mydoc.txt then the document information files would be docinfo.xml and mydoc-docinfo.xml (for DocBook outputs) and docinfo.html and mydoc-docinfo.html (for HTML outputs). The docinfo attributes control which docinfo files are included in the output files.

The contents docinfo templates and files is dependent on the type of output:

HTML
Valid head child elements. Typically style and script elements for CSS and JavaScript inclusion.
DocBook
Valid articleinfo or bookinfo child elements. DocBook defines numerous elements for document meta-data, for example: copyrights, document history and authorship information. See the DocBook ./doc/article-docinfo.xml example that comes with the AsciiDoc distribution. The rendering of meta-data elements (or not) is DocBook processor dependent.
Back to top