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.

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

	Tip
	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:

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

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

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

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.

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)

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 SGML/XML markups the ampersand, less than and greater than characters). The following example causes all occurrences of the < character to be replaced by <.

<=&lt;

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

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.

[replacements] and [replacements2] 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!

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:

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.

Configuration files have a .conf file name extension; they are loaded implicitly (using predefined file names and locations) or explicitly (using the asciidoc(1) -f (--conf-file) command-line option).

Implicit configuration files are loaded from the following directories in the following order:

The following implicit configuration files from each of the above locations are loaded in the following order:

Where <backend> and <doctype> are values specified by the asciidoc(1) -b (--backend) and -d (--doctype) command-line options.

Next, configuration files named like the source file will be automatically loaded if they are found in the source file directory. For example if the source file is mydoc.txt and the --backend=html4 option is used then asciidoc(1) will look for mydoc.conf and mydoc-html4.conf in that order.

Implicit configuration files that don’t exist will be silently skipped.

The user can explicitly specify additional configuration files using the asciidoc(1) -f (--conf-file) command-line option. The -f option can be specified multiple times, in which case configuration files will be processed in the order they appear on the command-line.

For example, when we translate our AsciiDoc document mydoc.txt with:

$ asciidoc -f extra.conf mydoc.txt

The last configuration file to load is the language configuration file lang-<lang>.conf. <lang> is the value of the AsciiDoc lang attribute (defaults to en (English)). You can set the lang attribute inside the AsciiDoc source file using an AttributeEntry provided it is the first entry and provided it precedes the document header, for example:

:lang: es

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