Chapter 26. Configuration Files

AsciiDoc source file syntax and output file markup is largely controlled by a set of cascading, text based, configuration files. At runtime The AsciiDoc default configuration files are combined with optional user and document specific configuration files.

26.1. Configuration File Format

Configuration files contain named sections. Each section begins with a section name in square brackets []. The section body consists of the lines of text between adjacent section headings.

Section names consist of one or more alphanumeric, underscore or dash characters and cannot begin or end with a dash.
Lines starting with a # character are treated as comments and ignored.
If the section name is prefixed with a + character then the section contents is appended to the contents of an already existing same-named section.
Otherwise same-named sections and section entries override previously loaded sections and section entries (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections and section entries that need to be overridden.


	When creating custom configuration files you only need to include the sections and entries that differ from the default configuration.


	The best way to learn about configuration files is to read the default configuration files in the AsciiDoc distribution in conjunction with `asciidoc(1)` output files. You can view configuration file load sequence by turning on the `asciidoc(1)` `-v` (`--verbose`) command-line option.

AsciiDoc reserves the following section names for specific purposes:

miscellaneous: Configuration options that don’t belong anywhere else.
attributes: Attribute name/value entries.
specialcharacters: Special characters reserved by the backend markup.
tags: Backend markup tags.
quotes: Definitions for quoted inline character formatting.
specialwords: Lists of words and phrases singled out for special markup.
replacements, replacements2, replacements3: Find and replace substitution definitions.
specialsections: Used to single out special section names for specific markup.
macros: Macro syntax definitions.
titles: Heading, section and block title definitions.
paradef-*: Paragraph element definitions.
blockdef-*: DelimitedBlock element definitions.
listdef-*: List element definitions.
listtags-*: List element tag definitions.
tabledef-*: Table element definitions.
tabletags-*: Table element tag definitions.

Each line of text in these sections is a section entry. Section entries share the following syntax:

name=value: The entry value is set to value.
name=: The entry value is set to a zero length string.
name!: The entry is undefined (deleted from the configuration). This syntax only applies to attributes and miscellaneous sections.

Section entry behavior

All equals characters inside the name must be escaped with a backslash character.
name and value are stripped of leading and trailing white space.
Attribute names, tag entry names and markup template section names consist of one or more alphanumeric, underscore or dash characters. Names should not begin or end with a dash.
A blank configuration file section (one without any entries) deletes any preceding section with the same name (applies to non-markup template sections).

26.2. Miscellaneous section

The optional [miscellaneous] section specifies the following name=value options:

newline

Output file line termination characters. Can include any valid Python string escape sequences. The default value is \r\n (carriage return, line feed). Should not be quoted or contain explicit spaces (use \x20 instead). For example:

$ asciidoc -a 'newline=\n' -b docbook mydoc.txt

outfilesuffix

The default extension for the output file, for example outfilesuffix=.html. Defaults to backend name.

tabsize

The number of spaces to expand tab characters, for example tabsize=4. Defaults to 8. A tabsize of zero suppresses tab expansion (useful when piping included files through block filters). Included files can override this option using the tabsize attribute.

pagewidth, pageunits

These global table related options are documented in the Table Configuration File Definitions sub-section.


	`[miscellaneous]` configuration file entries can be set using the `asciidoc(1)` `-a` (`--attribute`) command-line option.

26.3. Titles section

sectiontitle

Two line section title pattern. The entry value is a Python regular expression containing the named group title.

underlines

A comma separated list of document and section title underline character pairs starting with the section level 0 and ending with section level 4 underline. The default setting is:

underlines="==","--","~~","^^","++"

sect0…sect4

One line section title patterns. The entry value is a Python regular expression containing the named group title.

blocktitle

BlockTitle element pattern. The entry value is a Python regular expression containing the named group title.

subs

A comma separated list of substitutions that are performed on the document header and section titles. Defaults to normal substitution.

26.4. Tags section

The [tags] section contains backend tag definitions (one per line). Tags are used to translate AsciiDoc elements to backend markup.

An AsciiDoc tag definition is formatted like <tagname>=<starttag>|<endtag>. For example:

emphasis=<em>|</em>

In this example asciidoc(1) replaces the | character with the emphasized text from the AsciiDoc input file and writes the result to the output file.

Use the {brvbar} attribute reference if you need to include a | pipe character inside tag text.

26.5. Attributes section

The optional [attributes] section contains predefined attributes.

If the attribute value requires leading or trailing spaces then the text text should be enclosed in quotation mark (") characters.

To delete a attribute insert a name! entry in a downstream configuration file or use the asciidoc(1) --attribute name! command-line option (an attribute name suffixed with a ! character deletes the attribute)

26.6. Special Characters section

The [specialcharacters] section specifies how to escape characters reserved by the backend markup. Each translation is specified on a single line formatted like:

<special_character>=<translated_characters>

Special characters are normally confined to those that resolve markup ambiguity (in the case of HTML and XML markups the ampersand, less than and greater than characters). The following example causes all occurrences of the < character to be replaced by <.

<=&lt;

26.7. Quoted Text section

Quoting is used primarily for text formatting. The [quotes] section defines AsciiDoc quoting characters and their corresponding backend markup tags. Each section entry value is the name of a of a [tags] section entry. The entry name is the character (or characters) that quote the text. The following examples are taken from AsciiDoc configuration files:

[quotes]
_=emphasis

[tags]
emphasis=<em>|</em>

You can specify the left and right quote strings separately by separating them with a | character, for example:

``|''=quoted

Omitting the tag will disable quoting, for example, if you don’t want superscripts or subscripts put the following in a custom configuration file or edit the global asciidoc.conf configuration file:

[quotes]
^=
~=

Unconstrained quotes are differentiated from constrained quotes by prefixing the tag name with a hash character, for example:

__=#emphasis

Quoted text behavior

Quote characters must be non-alphanumeric.
To minimize quoting ambiguity try not to use the same quote characters in different quote types.

26.8. Special Words section

The [specialwords] section is used to single out words and phrases that you want to consistently format in some way throughout your document without having to repeatedly specify the markup. The name of each entry corresponds to a markup template section and the entry value consists of a list of words and phrases to be marked up. For example:

[specialwords]
strongwords=NOTE IMPORTANT

[strongwords]
<strong>{words}</strong>

The examples specifies that any occurrence of NOTE or IMPORTANT should appear in a bold font.

Words and word phrases are treated as Python regular expressions: for example, the word ^NOTE would only match NOTE if appeared at the start of a line.

AsciiDoc comes with three built-in Special Word types: emphasizedwords, monospacedwords and strongwords, each has a corresponding (backend specific) markup template section. Edit the configuration files to customize existing Special Words and to add new ones.

Special word behavior

Word list entries must be separated by space characters.
Word list entries with embedded spaces should be enclosed in quotation (") characters.
A [specialwords] section entry of the form name=word1 [word2…] adds words to existing name entries.
A [specialwords] section entry of the form name undefines (deletes) all existing name words.
Since word list entries are processed as Python regular expressions you need to be careful to escape regular expression special characters.
By default Special Words are substituted before Inline Macros, this may lead to undesirable consequences. For example the special word foobar would be expanded inside the macro call http://www.foobar.com[]. A possible solution is to emphasize whole words only by defining the word using regular expression characters, for example \bfoobar\b.
If the first matched character of a special word is a backslash then the remaining characters are output without markup i.e. the backslash can be used to escape special word markup. For example the special word \\?\b[Tt]en\b will mark up the words Ten and ten only if they are not preceded by a backslash.

26.9. Replacements section

[replacements], [replacements2] and [replacements3] configuration file entries specify find and replace text and are formatted like:

<find_pattern>=<replacement_text>

The find text can be a Python regular expression; the replace text can contain Python regular expression group references.

Use Replacement shortcuts for often used macro references, for example (the second replacement allows us to backslash escape the macro name):

NEW!=image:./images/smallnew.png[New!]
\\NEW!=NEW!

The only difference between the three replacement types is how they are applied. By default replacements and replacements2 are applied in normal substitution contexts whereas replacements3 needs to be configured explicitly and should only be used in backend configuration files.

Replacement behavior

The built-in replacements can be escaped with a backslash.
If the find or replace text has leading or trailing spaces then the text should be enclosed in quotation (") characters.
Since the find text is processed as a regular expression you need to be careful to escape regular expression special characters.
Replacements are performed in the same order they appear in the configuration file replacements section.

26.10. Markup Template Sections

Markup template sections supply backend markup for translating AsciiDoc elements. Since the text is normally backend dependent you’ll find these sections in the backend specific configuration files. Template sections differ from other sections in that they contain a single block of text instead of per line name=value entries. A markup template section body can contain:

Attribute references
System macro calls.
A document content placeholder

The document content placeholder is a single | character and is replaced by text from the source element. Use the {brvbar} attribute reference if you need a literal | character in the template.

26.11. Configuration file names, precedence and locations

Configuration files have a .conf file name extension; they are loaded from the following locations:

The directory containing the asciidoc executable.
If there is no asciidoc.conf file in the directory containing the asciidoc executable then load from the global configuration directory (normally /etc/asciidoc or /usr/local/etc/asciidoc) i.e. the global configuration files directory is skipped if AsciiDoc configuration files are installed in the same directory as the asciidoc executable. This allows both a system wide copy and multiple local copies of AsciiDoc to coexist on the same host PC.
The user’s $HOME/.asciidoc directory (if it exists).
The directory containing the AsciiDoc source file.
Explicit configuration files specified using:
- The conf-files attribute (one or more file names separated by a | character). These files are loaded in the order they are specified and prior to files specified using the --conf-file command-line option.
- The asciidoc(1) --conf-file) command-line option. The --conf-file option can be specified multiple times, in which case configuration files will be processed in the same order they appear on the command-line.
Backend plugin configuration files are loaded from subdirectories named like backends/<backend> in locations 1, 2 and 3.
Filter configuration files are loaded from subdirectories named like filters/<filter> in locations 1, 2 and 3.

Configuration files from the above locations are loaded in the following order:

The [attributes] section only from:
- asciidoc.conf in location 3
- Files from location 5.
  This first pass makes locally set attributes available in the global asciidoc.conf file.
asciidoc.conf from locations 1, 2, 3.
attributes, titles and specialcharacters sections from the asciidoc.conf in location 4.
The document header is parsed at this point and we can assume the backend and doctype have now been defined.
Backend plugin <backend>.conf and <backend>-<doctype>.conf files from locations 6. If a backend plugin is not found then try locations 1, 2 and 3 for <backend>.conf and <backend>-<doctype>.conf backend configuration files.
Filter conf files from locations 7.
lang-<lang>.conf from locations 1, 2, 3.
asciidoc.conf from location 4.
<backend>.conf and <backend>-<doctype>.conf from location 4.
Filter conf files from location 4.
<docfile>.conf and <docfile>-<backend>.conf from location 4.
Configuration files from location 5.

Where:

<backend> and <doctype> are values specified by the asciidoc(1) -b (--backend) and -d (--doctype) command-line options.
<infile> is the path name of the AsciiDoc input file without the file name extension.
<lang> is a two letter country code set by the the AsciiDoc lang attribute.

The backend and language global configuration files are loaded after the header has been parsed. This means that you can set most attributes in the document header. Here’s an example header:

Life's Mysteries
================
:author: Hu Nose
:doctype: book
:toc:
:icons:
:data-uri:
:lang: en
:encoding: iso-8859-1

Attributes set in the document header take precedence over configuration file attributes.


	Use the `asciidoc(1)` `-v` (`--verbose`) command-line option to see which configuration files are loaded and the order in which they are loaded.