5. Document Structure

Prev		Next

An AsciiDoc document consists of a series of block elements starting with an optional document Header, followed by an optional Preamble, followed by zero or more document Sections.

Almost any combination of zero or more elements constitutes a valid AsciiDoc document: documents can range from a single sentence to a multi-part book.

5.1. Block Elements

Block elements consist of one or more lines of text and may contain other block elements.

The AsciiDoc block structure can be informally summarized as follows ^[1]:

Document      ::= (Header?,Preamble?,Section*)
Header        ::= (Title,(AuthorInfo,RevisionInfo?)?)
AuthorInfo    ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
RevisionInfo  ::= (RevisionNumber?,RevisionDate,RevisionRemark?)
Preamble      ::= (SectionBody)
Section       ::= (Title,SectionBody?,(Section)*)
SectionBody   ::= ((BlockTitle?,Block)|BlockMacro)+
Block         ::= (Paragraph|DelimitedBlock|List|Table)
List          ::= (BulletedList|NumberedList|LabeledList|CalloutList)
BulletedList  ::= (ListItem)+
NumberedList  ::= (ListItem)+
CalloutList   ::= (ListItem)+
LabeledList   ::= (ListEntry)+
ListEntry     ::= (ListLabel,ListItem)
ListLabel     ::= (ListTerm+)
ListItem      ::= (ItemText,(List|ListParagraph|ListContinuation)*)

Where:

? implies zero or one occurrence, + implies one or more occurrences, * implies zero or more occurrences.
All block elements are separated by line boundaries.
BlockId, AttributeEntry and AttributeList block elements (not shown) can occur almost anywhere.
There are a number of document type and backend specific restrictions imposed on the block syntax.
The following elements cannot contain blank lines: Header, Title, Paragraph, ItemText.
A ListParagraph is a Paragraph with its listelement option set.
A ListContinuation is a list continuation element.

5.2. Header

The Header contains a document title plus optional authorship and revision information:

The Header is optional, but if it is used it must start with a document title.
The header can be preceded by comments and attribute entries.
Optional Author and Revision information immediately follows the header title.
The header can include attribute entries.
The document header must be separated from the remainder of the document by one or more blank lines.

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 consists of a first name followed by optional middle and last names separated by white space. Multi-word first, middle and last names can be entered in the header author line using the underscore as a word separator. The email address comes last and must be enclosed in angle <> brackets. Author names cannot contain angle <> bracket characters. Here a some examples of author information lines:

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

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

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 or attribute entry 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.
An RCS/CSV/SVN $Id$ marker (if an $Id$ revision marker is used the header author line can be omitted).

Here a some examples of header revision lines:

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.

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

The revnumber attribute can be an RCS/CSV/SVN $Id$ marker. Attributes can also be added to the header for substitution in the header template with Attribute Entry elements.

5.2.1. Additional document header information

DocBook defines numerous elements for document meta-data, for example: copyrights, document history and authorship information. The AsciiDoc header syntax provides for basic revision and author information — additional information such as copyrights, document history authorship details can be optionally included from a separate document information file. The document information file can contain any DocBook elements that are allowed inside the DocBook articleinfo and bookinfo elements:

The document information file must be in the same directory as the source document and must be named like <docname>-docinfo.xml. For example, if the source document is called mydoc.txt then the document information file would be named mydoc-docinfo.xml.
The document information file will only be included in the DocBook output if the docinfo attribute is defined, for example:
```
$ asciidoc -a docinfo -b docbook mydoc.txt
```
See the ./doc/article-docinfo.xml example that comes with the AsciiDoc distribution.
Similarly AsciiDoc will include a docinfo file named like <docname>-docinfo.html (if it exists) into HTML backend outputs. In the case of HTML outputs however it’s usually easier to put AsciiDoc markup in your source file directly after the header.

	Note
	DocBook has a rich set of meta data elements, just which of these elements are rendered is DocBook processor dependent.

5.3. Preamble

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

5.4. Sections

In addition to the document title (level 0), AsciiDoc supports four section levels: 1 (top) to 4 (bottom). Section levels are delimited by section titles. Sections are translated using configuration file section markup templates. AsciiDoc generates the following intrinsic attributes specifically for use in section markup templates:

level: The level attribute is the section level number, it is normally just the title level number (1..4). However, if the leveloffset attribute is defined it will be added to the level attribute. The leveloffset attribute is useful for combining documents.
sectnum: The -n (--section-numbers) command-line option generates the sectnum (section number) attribute. The sectnum attribute is used for section numbers in HTML outputs (DocBook section numbering are handled automatically by the DocBook toolchain commands).

5.4.1. Section markup templates

Section markup templates specify output markup and are defined in AsciiDoc configuration files. Section markup template names are derived as follows (in order of precedence):

From the title’s first positional attribute or template attribute. For example, the following three section titles are functionally equivalent:

[[terms]]
[glossary]
List of Terms
-------------

["glossary",id="terms"]
List of Terms
-------------

[template="glossary",id="terms"]
List of Terms
-------------

When the title text matches a configuration file [specialsections] entry.
If neither of the above the default sect<level> template is used (where <level> is a number from 1 to 4).

In addition to the normal section template names (sect1, sect2, sect3, sect4) AsciiDoc has the following templates for frontmatter, backmatter and other special sections: abstract, preface, colophon, dedication, glossary, bibliography, synopsis, appendix, index. These special section templates generate the corresponding Docbook elements; for HTML outputs they default to the sect1 section template.

5.4.2. Section IDs

If no explicit section ID is specified an ID will be synthesised from the section title. The primary purpose of this feature is to ensure persistence of table of contents links (permalinks): the missing section IDs are generated dynamically by the JavaScript TOC generator after the page is loaded. If you link to a dynamically generated TOC address the page will load but the browser will ignore the (as yet ungenerated) section ID.

The IDs are generated by the following algorithm:

Replace all non-alphanumeric title characters with underscores.
Strip leading or trailing underscores.
Convert to lowercase.
Prepend the idprefix attribute (so there’s no possibility of name clashes with existing document IDs). Prepend an underscore if the idprefix attribute is not defined.
A numbered suffix (_2, _3 …) is added if a same named auto-generated section ID exists.

For example the title Jim’s House would generate the ID _jim_s_house.

Section ID synthesis can be disabled by undefining the sectids attribute.

5.4.3. Special Section Titles

AsciiDoc has a mechanism for mapping predefined section titles auto-magically to specific markup templates. For example a title Appendix A: Code Reference will automatically use the appendix section markup template. The mappings from title to template name are specified in [specialsections] sections in the Asciidoc language configuration files (lang-*.conf). Section entries are formatted like:

<title>=<template>

<title> is a Python regular expression and <template> is the name of a configuration file markup template section. If the <title> matches an AsciiDoc document section title then the backend output is marked up using the <template> 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 whole of the AsciiDoc section title. If <template> is blank then any existing entry with the same <title> will be deleted.

Special section titles vs. explicit template names

AsciiDoc has two mechanisms for specifying non-default section markup templates: you can specify the template name explicitly (using the template attribute) or indirectly (using special section titles). Specifying a section template attribute explicitly is preferred. Auto-magical special section titles have the following drawbacks:

They are non-obvious, you have to know the exact matching title for each special section on a language by language basis.
Section titles are predefined and can only be customised with a configuration change.
The implementation is complicated by multiple languages: every special section title has to be defined for each language (in each of the lang-*.conf files).

Specifying special section template names explicitly does add more noise to the source document (the template attribute declaration), but the intention is obvious and the syntax is consistent with other AsciiDoc elements c.f. bibliographic, Q&A and glossary lists.

Special section titles have been deprecated but are retained for backward compatibility.

5.5. Inline Elements

Inline document elements are used to format text and to perform various types of text substitution. Inline elements and inline element syntax is defined in the asciidoc(1) configuration files.

Here is a list of AsciiDoc inline elements in the (default) order in which they are processed:

Special characters: These character sequences escape special characters used by the backend markup (typically <, >, and & characters). See [specialcharacters] configuration file sections.
Quotes: Elements that markup words and phrases; usually for character formatting. See [quotes] configuration file sections.
Special Words: Word or word phrase patterns singled out for markup without the need for further annotation. See [specialwords] configuration file sections.
Replacements: Each replacement defines a word or word phrase pattern to search for along with corresponding replacement text. See [replacements] configuration file sections.
Attribute references: Document attribute names enclosed in braces are replaced by the corresponding attribute value.
Inline Macros: Inline macros are replaced by the contents of parametrized configuration file sections.

^[1]This is a rough structural guide, not a rigorous syntax definition