AsciiDoc User Guide

Here's an example AsciiDoc document header:

Writing Documentation using AsciiDoc

====================================

Stuart Rackham <[e-mail]> v2.0, February 2003

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

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

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

Preamble

The Preamble is an optional untitled section body between the document Header and the first Section title.

Sections

AsciiDoc supports five section levels 0 to 4 (although only book documents are allowed to contain level 0 sections). Section levels are delineated by the section titles.

Sections are translated using configuration file markup templates. To determine which configuration file template to use AsciiDoc first searches for special section titles in the [specialsections] configuration entries, if not found it uses the [sect<level>] template.

The -n (—section-numbers) command-line option auto-numbers HTML outputs (DocBook line numbering is handled automatically by the DocBook toolchain commands).

Special Sections

In addition to normal sections, documents can contain optional frontmatter and backmatter sections — for example: preface, bibliography, table of contents, index.

The AsciiDoc configuration file [specialsections] section specifies special section titles and the corresponding backend markup templates.

[specialsections] entries are formatted like:

<pattern>=<name>

<pattern> is a Python regular expression and <name> is the name of a configuration file markup template section. If the <pattern> matches an AsciiDoc document section title then the backend output is marked up using the <name> markup template (instead of the default sect<level> section template). The {title} attribute value is set to the value of the matched regular expression group named title, if there is no title group {title} defaults to the the whole of the AsciiDoc section title.

AsciiDoc comes preconfigured with the following special section titles:

11