AsciiDoc User Guide

Examples of AsciiDoc markup are scattered throughout this document but the best way to quickly get a feel for AsciiDoc is to view the AsciiDoc web site and/or distributed examples:

AsciiDoc generates DocBook article, book and refentry documents (corresponding to the asciidoc(1) article, book and manpage document types).

As of version 4.2 the -b docbook command-line option switched from outputting DocBook SGML to the newer DocBook XML. You can still produce DocBook SGML using the -b docbook-sgml command-line option.

The DocBook DTD restricts the allowable AsciiDoc syntax:

The asciidoc(1) -b xhtml command-line option produces plain unstyled XHTML 1.0 markup that can be viewed on any modern web browser.

A minor variation of xhtml — the asciidoc(1) -b html command-line option produces HTML 4 markup.

The asciidoc(1) -b css command-line option produces XHTML 1.0 conformant output styled with linked CSS2 stylesheets.

The main.css, article.css and manpage.css stylesheets (located in the ./stylesheets/ directory) style both screen and printed outputs. Edit the stylesheets to customize your document's appearance.

	Note
	Browser CSS support varies from browser to browser. The examples work well on IE6, Firefox 1.0 and up, Mozilla 1.1 and up, Opera 7 and Konqueror 3.01 but have not been tested on other browsers. All browsers have their quirks. When it comes to implementing CSS, of those tested I found Mozilla and Firefox to be the most conformant.

The asciidoc(1) -b css-embedded command-line option produces XHTML 1.0 conformant output styled with embedded CSS2 stylesheets. Similar to the css backend but translated files do not rely on external stylesheets.

The LinuxDoc DTD restricts the allowable AsciiDoc syntax:

The default xmlto(1) and jw(1) outputs are quite plain (compared to the distributed AsciiDoc HTML and PDF documentation files). The Processing DocBook Files section explains how you can generate nicely styled output using custom DocBook XSL Stylesheets drivers. This is the best route for generating PDF outputs.

	Warning
	I don't recommend using xmlto(1) for producing PDF — the output is not bookmarked and callouts generate LaTeX errors.

If you use jw(1) don't forget to specify the docbook-sgml backend, not the docbook backend. This example converts the asciidoc.txt AsciiDoc User Guide to PDF format:

$ asciidoc -b docbook-sgml asciidoc.txt
$ jw -b pdf asciidoc.sgml

To convert the asciidoc.1.txt AsciiDoc manpage document to native man page groff(1) man macro package format:

$ asciidoc -d manpage -b docbook asciidoc.1.txt
$ xmlto man asciidoc.1.xml

To view the man page file as it would be displayed by the man(1) command:

$ groff -mandoc -Tascii asciidoc.1 | less

To print a high quality man page to a postscript printer:

$ groff -mandoc -Tps asciidoc.1 | lpr

You can also produce HTML from DocBook files:

$ asciidoc -b docbook asciidoc.txt
$ xmlto html-nochunks asciidoc.xml      # Single HTML file.
$ xmlto html -o chunked asciidoc.xml    # Chunked HTML file.

LinuxDoc is an SGML documentation markup language originally created by Matt Welsh to write Linux documentation. LinuxDoc does a good job of marking up small and medium sized text based documents. Its strength is its simplicity and ease of use. Nowadays LinuxDoc has been largely superseded by DocBook.

	Note
	LinuxDoc limitations place restrictions on the use of a number of AsciiDoc elements.

There are a number of Open Source applications available to convert the LinuxDoc SGML markup to various presentation formats, here are a couple of examples:

Create a single HTML file with a detailed table of contents using the linuxdoc(1) command that comes with the Linuxdoc-Tools package.

$ linuxdoc -B html -s 0 -T 2 mydocument.sgml

Generate a set of linked HTML files using the sgmlfmt(1) from the FreeBSD sgmlformat package:

$ sgmlfmt -f html mydocument.sgml

Create a PDF file using the sgmlfmt(1) from the FreeBSD sgmlformat package:

$ sgmlfmt -f ps mydocument.sgml
$ ps2pdf asciidoc.ps

AsciiDoc does not have a text backend (for most applications AsciiDoc source text is fine), however you can convert asciidoc(1) generated HTML and DocBook files to text.

You can use the lynx(1) web browser to convert AsciiDoc generated HTML to text. You'll find an asciidoc2text.sh shell script included in the AsciiDoc distribution examples/asciidoc2text directory which, together with the asciidoc2text.conf configuration file, automates text file generation with a single command. For example:

$ ./examples/asciidoc2text/asciidoc2text.sh test.txt >test.text

You can also use jw(1) and xmlto(1) toolchain commands to convert DocBook to text.

	Warning
	By default both jw(1) and xmlto(1) commands create files with a .txt extension when generating text files. This will overwrite your AsciiDoc *.txt source files (use the -o command-line option to output to an alternative directory).

Used for short documents, articles and general documentation. See the article.txt example AsciiDoc article in the distribution ./doc directory.

Books share the same format as articles; in addition there is the option to add level 0 sections to divide a book into multiple parts.

Book documents will normally be used to produce DocBook output since DocBook processors can automatically generate footnotes, table of contents, list of tables, list of figures, list of examples and indexes.

AsciiDoc markup supports all the standard DocBook frontmatter and backmatter special sections (dedication, preface, bibliography, glossary, index, colophon) plus footnotes and index entries.

Used to generate UNIX manual pages. AsciiDoc manpage documents observe special header title and section naming conventions — see the Manpage Documents section for details.

The asciidoc(1) man page (asciidoc.1.txt in the AsciiDoc distribution ./doc directory) is an example of an AsciiDoc man page file.

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

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

Document      ::= (Header?,Preamble?,Section*)
Header        ::= (Title,(AuthorLine,RevisionLine?)?)
AuthorLine    ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
RevisionLine  ::= (Revision?,Date)
Preamble      ::= (SectionBody)
Section       ::= (Title,SectionBody?,(Section)*)
SectionBody   ::= ((BlockTitle?,
                  (Paragraph|DelimitedBlock|List|Table|BlockMacro))+)
List          ::= (BulletedList|NumberedList|LabeledList|CalloutList)
BulletedList  ::= (ListItem)+
NumberedList  ::= (ListItem)+
CalloutList   ::= (ListItem)+
LabeledList   ::= (ItemLabel+,ListItem)+
ListItem      ::= (ItemText,((List|ListParagraph)?,ItemContinuation?)*)
Table         ::= (Ruler,TableHeader?,TableBody,TableFooter?)
TableHeader   ::= (TableRow+,TableUnderline)
TableFooter   ::= (TableRow+,TableUnderline)
TableBody     ::= (TableRow+,TableUnderline)
TableRow      ::= (TableData+)

The Header is optional but and starts on first line of the document beginning with a document title. Immediately following the title are optional Author and Revision lines.

The author 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. The email address is last and must be enclosed in angle <> brackets. Author names cannot contain angle <> bracket characters.

The optional document header revision line should immediately follow the author line. The revision line can be one of two formats:

The document heading is separated from the remainder of the document by one or more blank lines.

Here's an example AsciiDoc document header:

Writing Documentation using AsciiDoc
====================================
Stuart Rackham <srackham@methods.co.nz>
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 command-line option. For example:

$ asciidoc -b docbook -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.

The Preamble is an optional untitled section body between the document Header and the first Section title. The Preamble should only be included in article documents.

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

A section consists of a section title followed by an optional section body.

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

You can the -n command-line option to auto-number HTML outputs (DocBook line numbering is handled automatically by the DocBook toolchain commands).

<pattern>=<name>

Preface                    (book documents only)
Abstract                   (article documents only)
Dedication                 (book documents only)
Glossary
Bibliography|References
Colophon                   (book documents only)
Index
Appendix [A-Z][:.] <title>

Inline document elements occur within block elements; inline elements can begin and end anywhere within a line but cannot span multiple lines.

Inline elements are used to markup character formatting and 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:

Words and phrases can be formatted by enclosing the text with predefined quoting characters:

Quoting characters can be changed and new quoting markup syntax defined by editing asciidoc(1) configuration files. See the Configuration Files section for details.

Put carets on either side of the text to be superscripted, put tildes on either side of text to be subscripted. For example, the following line:

e^{amp}#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
and ~some sub text~

Is rendered like:

e^πi+1 = 0. H₂O and x¹⁰. Some ^{super text} and _{some sub text}

If you want to display caret (^) or tilde (~) characters you need to ensure only one per line otherwise they'll be misinterpreted as superscripting and subscripting.

Superscripts and subscripts are implemented as Replacements substitutions.

A plus character preceded by at least one space character at the end of a line forces a line break. It generates an HTML line break (<br/>) tag. Line breaks are ignored when outputting to DocBook since it has no line break element.

A line of three or more apostrophe characters will generate an HTML ruler (<hr/>) tag. Ignored when generating non-HTML output formats.

By default tab characters input files will translated to 8 spaces. Tab expansion is set with the tabsize entry in the configuration file [miscellaneous] section and can be overridden in the include block macro by setting a tabsize attribute in the macro's attribute list. For example:

include::addendum.txt[tabsize=2]

The tab size can also be set using the -a command-line option, for example -a tabsize=4

The following replacements are defined in the default AsciiDoc configuration:

(C) copyright, (TM) trademark, (R) registered trademark,
-- em dash, ... ellipsis.

Is rendered as:

© copyright, ™ trademark, ® registered trademark, — em dash, … ellipsis.

The Configuration Files section explains how to configure your own replacements.

Words defined in [specialwords] configuration file sections are automatically marked up without having to be explicitly notated.

The Configuration Files section explains how to add and replace special words.

A two line title consists of a title line, starting hard against the left margin, and an underline. Section underlines consist a repeated character pairs spanning the width of the preceding title (give or take up to three characters):

The default title underlines for each of the document levels are:

Level 0 (top level):     ======================
Level 1:                 ----------------------
Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level):  ++++++++++++++++++++++

Examples:

Level One Section Title
-----------------------

Level 2 Subsection Title
~~~~~~~~~~~~~~~~~~~~~~~~

One line titles consist of a line starting with one or more equals characters (the exact number specified the section level) followed by a space followed by the section title. Here are some examples:

= Document Title
== Section level 1 title (top level section)
=== Section level 2 title
==== Section level 3 title
===== Section level 4 title

The syntax can be changed by editing the configuration file [titles] section sect0…sect4 entries.

A Default paragraph ([paradef-default]) consists of one or more non-blank lines of text. The first line must start hard against the left margin (no intervening white space). The processing expectation of the default paragraph type is that of a normal paragraph of text.

An Literal paragraph ([paradef-literal]) consists of one or more lines of text, where the first line is indented by one or more or space or tab characters. Literal paragraphs are rendered verbatim in a monospaced font usually without any distinguishing background or border. There is no text formatting or substitutions within Literal paragraphs apart from Special Characters and Callouts. For example:

Consul necessitatibus per id,
consetetur, eu pro everti postulant
homero verear ea mea,
qui. Movet blandit mea at,
interesset at has, eu nec.

Tip, Note, Important, Warning and Caution paragraph definitions support the corresponding DocBook admonishment elements, just write a normal paragraph but place NOTE:, TIP:, IMPORTANT:, WARNING: or CAUTION: as the first word of the paragraph. For example:

NOTE: This is an example note.

Renders:

	Note
	This is an example note.

	Tip
	If your admonition is more than a single paragraph use one of the admonition variants of the ExampleBlock.

Paragraph translation is controlled by [paradef*] configuration file section entries. Users can define new types of paragraphs and modify the behavior of existing types by editing AsciiDoc configuration files.

Here is the shipped Default paragraph definition:

[paradef-default]
delimiter=(?P<text>\S.*)
template=paragraph

The Default paragraph definition has a couple of special properties:

Available paragraph definition entries:

Bulleted list items start with a dash followed by a space or tab character. Bulleted list syntaxes are:

- List item.
* List item.

Numbered list items start with an optional number or letter followed by a period followed by a space or tab character. List numbering is optional. Numbered list syntaxes are:

.  Integer numbered list item.
1. Integer numbered list item with optional numbering.
.. Lowercase letter numbered list item.
a. Lowercase letter numbered list item with optional numbering.

Here are some examples:

- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  * Fusce euismod commodo velit.
  * Qui in magna commodo, est labitur dolorum an. Est ne magna primis
    adolescens. Sit munere ponderum dignissim et. Minim luptatum et
    vel.
  * Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc consequat lobortis.
- Nulla porttitor vulputate libero.
  . Fusce euismod commodo velit.
  . Vivamus fringilla mi eu lacus.
    .. Fusce euismod commodo velit.
    .. Vivamus fringilla mi eu lacus.
  . Donec eget arcu bibendum nunc consequat lobortis.
- Praesent eget purus quis magna eleifend eleifend.
  1. Fusce euismod commodo velit.
    a. Fusce euismod commodo velit.
    b. Vivamus fringilla mi eu lacus.
    c. Donec eget arcu bibendum nunc consequat lobortis.
  2. Vivamus fringilla mi eu lacus.
  3. Donec eget arcu bibendum nunc consequat lobortis.
  4. Nam fermentum mattis ante.

Which render as:

Labeled list items consist of one or more text labels followed the text of the list item.

An item label begins a line with an alphanumeric character hard against the left margin and ends with a double colon :: or semi-colon ;;.

The list item text consists of one or more lines of text starting on the line immediately following the label and can be followed by nested List or ListParagraph elements. Item text can be optionally indented.

Here are some examples:

Lorem::
  Fusce euismod commodo velit.

  Fusce euismod commodo velit.

Ipsum::
  Vivamus fringilla mi eu lacus.
  * Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc consequat lobortis.
Dolor::
  Donec eget arcu bibendum nunc consequat lobortis.
  'Suspendisse';;
    A massa id sem aliquam auctor.
  'Morbi';;
    Pretium nulla vel lorem.
  'In';;
    Dictum mauris in urna.

Which render as:

Horizontal labeled lists differ from vertical labeled lists in that the label and the list item sit side-by-side as opposed to the item under the label. Item text must begin on the same line as the label. For example:

	Tip
	Used vertical labeled lists in preference to horizontal labeled lists — current PDF rendering tools do not make a good job of determining the relative column widths.

Here are some examples:

*Lorem*:: Fusce euismod commodo velit.
  Qui in magna commodo, est labitur dolorum an. Est ne magna primis
  adolescens.

  Fusce euismod commodo velit.

*Ipsum*:: Vivamus fringilla mi eu lacus.
  * Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc consequat lobortis.
*Dolor*:: Donec eget arcu bibendum nunc consequat lobortis.
  Sit munere ponderum dignissim et. Minim luptatum et vel.
  'Suspendisse';; A massa id sem aliquam auctor.
  'Morbi';;       Pretium nulla vel lorem.
  'In';;          Dictum mauris in urna.

Which render as:

Fusce euismod commodo velit.

AsciiDoc comes pre-configured with a labeled list (?? label delimiter) for generating question and answer (Q&A) lists. Example:

Question one??
        Answer one.
Question two??
        Answer two.

AsciiDoc comes pre-configured with a labeled list (:- label delimiter) for generating glossary lists. Example:

A glossary term:-
    The corresponding definition.
A second glossary term:-
    The corresponding definition.

For working examples see the article.txt and book.txt documents in the AsciiDoc ./doc distribution directory.

	Note
	Glossary lists must be located in a glossary section to generate valid DocBook output.

AsciiDoc comes with a predefined itemized list (+ item bullet) for generating bibliography entries. Example:

+ [[[taoup]]] Eric Steven Raymond. 'The Art of Unix
  Programming'. Addison-Wesley. ISBN 0-13-142901-9.
+ [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
  'DocBook - The Definitive Guide'. O'Reilly & Associates.
  1999. ISBN 1-56592-580-7.

The [[[<reference>]]] syntax is a bibliography entry anchor, it generates an anchor named <reference> and additionally displays [<reference>] at the anchor position. For example [[[taoup]]] generates an anchor named taoup that displays [taoup] at the anchor position. Cite the reference from elsewhere your document using <<taoup>>, this displays a hyperlink ([taoup]) to the corresponding bibliography entry anchor.

For working examples see the article.txt and book.txt documents in the AsciiDoc ./doc distribution directory.

	Note
	Bibliography lists must be located in a bibliography section to generate valid DocBook output.

To include subsequent block elements in list items (in addition to implicitly included nested lists and Literal paragraphs) place a separator line containing a single plus character between the list item and the ensuing element. Multiple block elements (excluding section Titles and BlockTitles) may be included in a list item using this technique. For example:

Here's an example of list item continuation:

1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item one continued with a third paragraph.

2. List item two.

   List item two literal paragraph (no continuation required).

-  Nested list (item one).

   Nested list literal paragraph (no continuation required).
+
Nested list appended list item one paragraph

-  Nested list item two.

Renders:

A List Continuation block is a special delimited block which is functionally equivalent to List Item Continuation except that list items contained within the block do not require explicit + list item continuation lines:

The List Continuation Block is an experimental feature and is useful for lists with long multi-element list items. The alternative List Item Continuation is arguably uglier but is more obvious when reading AsciiDoc source — if you don't have strong feelings either way use explicit list continuation.

Example:

.List Block
--
1. List item one.

List item one continued with a second paragraph followed by an
Indented block.

.................
$ ls *.sh
$ mv *.sh ~/tmp
.................

List item one continued with a third paragraph.

2. List item two.

This paragraph is part of list item 2.
--

List behavior and syntax is determined by [listdef*] configuration file sections. The user can change existing list behavior and add new list types by editing configuration files.

List definition sections are characterized by the following entries:

The tag entries map the AsciiDoc list structure to backend HTML/SGML/XML markup; see the shipped AsciiDoc .conf configuration files for examples.

AsciiDoc ships with a number of predefined DelimitedBlocks (see the asciidoc.conf configuration file in the asciidoc(1) program directory):

Predefined delimited block underlines:

CommentBlock:  //////////////////////////
BackendBlock:  ++++++++++++++++++++++++++
ListingBlock:  --------------------------
LiteralBlock:  ..........................
SidebarBlock:  **************************
QuoteBlock:    __________________________

ListingBlocks are rendered verbatim in a monospaced font, they retain line and whitespace formatting and often distinguished by a background or border. There is no text formatting or substitutions within Listing blocks apart from Special Characters and Callouts. Listing blocks are often used for code and file listings.

Here's an example:

--------------------------------------
#include <stdio.h>

int main() {
        printf("Hello World!\n");
        exit(0);
}
--------------------------------------

Which will be rendered like:

#include <stdio.h>

int main() {
        printf("Hello World!\n");
        exit(0);
}

LiteralBlocks behave just like LiteralParagraphs except you don't have to indent the contents.

LiteralBlocks can be used to resolve list ambiguity. If the following list was indented it would be processed as an ordered list (not an indented paragraph):

....................
1. Item 1
2. Item 2
....................

Renders:

1. Item 1
2. Item 2

A sidebar is a short piece of text presented outside the narrative flow of the main text. The sidebar is normally presented inside a bordered box to set it apart from the main text.

The sidebar body is treated like a normal section body.

Here's an example:

.An Example Sidebar
************************************************
Any AsciiDoc SectionBody element (apart from
SidebarBlocks) can be placed inside a sidebar.
************************************************

Which will be rendered like:

Sidebar elements are not supported by the LinuxDoc format and sidebar text appears as part of the main document flow.

CommentBlocks are not processed; they are useful for annotations and for excluding new or outdated content that you don't want displayed. Here's and example:

//////////////////////////////////////////
CommentBlock contents are not processed by
asciidoc(1).
//////////////////////////////////////////

See also Comment Lines.

BackendBlocks are for backend specific markup, text is only subject to attribute and macro substitution. BackendBlock content will generally be backend specific. Here's an example:

++++++++++++++++++++++++++++++++++++++
<table border="1"><tr>
  <td>Cell 1</td>
  <td>Cell 2</td>
</tr></table>
++++++++++++++++++++++++++++++++++++++

QuoteBlocks are used for quoted passages of text. attribution and citetitle named attributes specify the author and source of the quote (they are equivalent to positional attribute list entries 1 and 2 respectively). Both attributes are optional and the block body is treated like a SectionBody. For example:

[Bertrand Russell, The World of Mathematics (1956)]
____________________________________________________________________
A good notation has subtlety and suggestiveness which at times makes
it almost seem like a live teacher.
____________________________________________________________________

Which is rendered as:

In this example unquoted positional attributes have been used, the following quoted positional and named attributes are equivalent (if the attribute list contained commas then quoting would have been mandatory):

["Bertrand Russell","The World of Mathematics (1956)"]
[attribution="Bertrand Russell",citetitle="The World of Mathematics (1956)"]

ExampleBlocks encapsulate the DocBook Example element and are used, well, for examples. DocBook processors automatically number examples and generate a list of examples backmatter section.

Example blocks are delimited by lines of equals characters and you can put any block elements apart from Titles, BlockTitles and Sidebars) inside an example block. AsciiDoc example blocks allow variant delimited blocks.

As a point of interest, AsciiDoc automatically wraps the following titled (preceded by a TitleBlock) AsciiDoc elements in a DocBook example element: LiteralParagraph, LiteralBlock, ListingBlock.

Variant blocks provide a mechanism for varying the behavior of a delimited block. If the block's definition has been assigned the variants option and it's attribute list includes attribute {1} then it will be used as a prefix for the block's markup template name — the name of the markup template is a lowercased {1}block.

The ExampleBlock is configured as variant block and can be used to generate admonition blocks (admonitions requiring more than just a simple admonition paragraph) by prefixing an AttributeList and setting the first attribute entry to NOTE, TIP, WARNING, IMPORTANT or CAUTION.

The following example uses the markup template configuration file section named [noteblock]:

[NOTE]
.An example note block
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.

. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
  .. Fusce euismod commodo velit.
  .. Vivamus fringilla mi eu lacus.
. Donec eget arcu bibendum
  nunc consequat lobortis.
=====================================================================

Renders:

	An example note block
	Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Fusce euismod commodo velit. Vivamus fringilla mi eu lacus. Fusce euismod commodo velit. Vivamus fringilla mi eu lacus. Donec eget arcu bibendum nunc consequat lobortis.

As an example, here is the default configuration file ListingBlock definition:

[blockdef-listing]
delimiter=^-{3,}$
template=listingblock
presubs=specialcharacters,callouts

DelimitedBlock processing proceeds as follows:

	Tip
	Attribute expansion is performed on the block filter command before it is executed, this is useful for passing arguments to the filter.

Callout marks are generated by the callout inline macro while callout lists are generated using the callout list definition. The callout macro and callout list are special in that they work together. The callout inline macro is not enabled by the normal macros substitutions option, instead it has it's own callouts substitution option.

The following attributes are available during inline callout macro substitution:

The {coids} attribute can be used during callout list item substitution — it is a space delimited list of callout IDs that refer to the explanatory list item.

Inline Macros occur in an inline element context. Predefined Inline macros include URL, image and link macros.

URLs

Standard http, https, ftp, file and mailto URLs are rendered using predefined inline macros.

The default AsciiDoc inline macro syntax is very similar to a URL: all you need to do is append an attribute list containing an optional caption immediately following the URL. If no text is inside the list the URL itself supplies the displayed text.

Here are some examples:

http://www.methods.co.nz/asciidoc/[The AsciiDoc home page]
mailto:joe.bloggs@foobar.com[email Joe Bloggs]
mailto:joe.bloggs@foobar.com[]

Which are rendered:

The AsciiDoc home page

email Joe Bloggs

joe.bloggs@foobar.com

	Tip
	If the <target> has space characters they should be replaced by %20. For example large%20image.png.

[[<id>,<xreflabel>]]
anchor:<id>[<xreflabel>]

[[X1]]

<<<id>,<caption>>>
xref:<id>[<caption>]

<<X15,attribute lists>>

link:<target>[<caption>]

link:downloads/foo.zip[download foo.zip]

image:<target>[<attributes>]

A Block macro reference must be contained in a single line separated either side by a blank line or a block delimiter.

Block macros behave just like Inline macros, with the following differences:

image::<target>[<attributes>]

.Main circuit board
image::images/layout.png[J14P main circuit board]

// This is a comment.

System macros are block macros that perform a predefined task which is hardwired into the asciidoc(1) program.

  include::chapter1.txt[tabsize=4]

  +++++++++++++++++++++++
  include1::table6.html[]
  +++++++++++++++++++++++

ifdef::<attribute>[]
:
endif::<attribute>[]

ifndef::<attribute>[]
:
endif::<attribute>[]

--------------------
sys::[ls -ltr *.txt]
--------------------

Each entry in the configuration [macros] section is a macro definition which can take one of the following forms:

<pattern> is a Python regular expression and <name> is the name of a markup template. If <name> is omitted then it is the value of the named regular expression match group named name.

The following annotated examples are all you'll need to start creating your own tables.

The only non-obvious thing you'll need to remember are the column stop characters:

Simple table:

`---`---
1   2
3   4
5   6
--------

Output:

Table with title, header and footer:

.An example table
[grid="all"]
'---------.--------------
Column 1   Column 2
-------------------------
1          Item 1
2          Item 2
3          Item 3
-------------------------
6         Three items
-------------------------

Output:

Four columns totaling 15% of the pagewidth, CSV data:

[frame="all"]
````~15
1,2,3,4
a,b,c,d
A,B,C,D
~~~~~~~~

Output:

A table with a numeric ruler and externally sourced CSV data:

[frame="all", grid="all"]
.15`20`25`20`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ID,Customer Name,Contact Name,Customer Address,Phone
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
include::customers.csv[]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Renders:

This sub-section details the AsciiDoc source file table format.

Table  ::= (Ruler,Header?,Body,Footer?)
Header ::= (Row+,Underline)
Footer ::= (Row+,Underline)
Body   ::= (Row+,Underline)
Row    ::= (Data+)

A table is terminated when the table underline is followed by a blank line or an end of file. Table underlines which separate table headers, bodies and footers should not be followed by a blank line.

ruler ::= ((colstop,(colwidth,fillchar+)?)+, fillchar+, tablewidth?

( N / M ) * pagewidth

( N / textwidth ) * pagewidth

Read on if you want to modify existing table behavior or create your own table definitions.

A table definition consists of two configuration file sections:

The easiest way to get a feel for how it all fits together is to take a look at the distributed AsciiDoc table definitions in the asciidoc.conf and backend configuration files.

Backend independent [tabledef-*] section entries are:

Backend specific [tabledef-*] section entries are:

The following attributes are available to the table markup template:

In addition tables are affected by the following [miscellaneous] configuration file entries:

The document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

The first manpage section is mandatory and must be called NAME and contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

printf, fprintf, sprintf - print formatted output

The second manpage section is mandatory and must be called SYNOPSIS.

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(1) program directory along with generated backend output and the backend markup spec. You view configuration file processing by turning on the asciidoc(1) -v command-line option.

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. A markup template section body can contain:

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

AsciiDoc reserves the following predefined, or Special, section names for specific purposes:

Each line of text in a Special section is a section entry. Section entries can take the following forms:

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 document and user specific configuration files.

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 hash character "#" are treated as comments and ignored.
• Same named sections and section entries override sections and section entries from previously loaded configuration files (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections or section entries that need to be overridden.
• Same named sections from different documents are merged automatically.

	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(1) program directory along with generated backend output and the backend markup spec. You view configuration file processing by turning on the asciidoc(1) -v command-line option.

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. A markup template section body can contain:

• Backend markup
• Attribute references
• A document content placeholder

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

Special Sections

AsciiDoc reserves the following predefined, or Special, section names for specific purposes:

miscellaneous

Configuration options that don't belong anywhere else.

attributes

Named substitution values.

specialcharacters

Special characters reserved by the backend markup.

tags

Markup tag definitions used by AsciiDoc markup mechanisms.

quotes

Definitions for inline character formatting quoting.

specialwords

Lists of words and phrases singled out for special markup.

replacements

Find and replace substitution definitions.

specialsections

Used to single out section names for special markup.

macros

Macro syntax definitions. titles: Heading, section and block title parameters.

paradef*

Paragraph element definitions.

blockdef*

DelimitedBlock element definitions.

listdef*

List element definitions.

tabledef*

Table element definitions.

Each line of text in a Special section is a section entry. Section entries can take the following forms:

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).

Section entry behavior

• All equalo to the native roff man page format (or other formats).

  For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc directory was used to generate both asciidoc.1.css-embedded.html HTML file and (via the xmlto(1) command) the asciidoc.1 roff formatted asciidoc(1) man page.

  To find out more about man pages view the man(7) manpage (man 7 man command).

  Document Heading

  The document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

  The NAME Section

  The first manpage section is mandatory and must be called NAME and contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

  printf, fprintf, sprintf - print formatted output
  

  The SYNOPSIS Section

  The second manpage section is mandatory and must be called SYNOPSIS.

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 document and user specific configuration files.

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 hash character "#" are treated as comments and ignored.
• Same named sections and section entries override sections and section entries from previously loaded configuration files (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections or section entries that need to be overridden.
• Same named sections from different documents are merged automatically.

	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(1) program directory along with generated backend output and the backend markup spec. You view configuration file processing by turning on the asciidoc(1) -v command-line option.

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. A markup template section body can contain:

• Backend markup
• Attribute references
• A document content placeholder

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

Special Sections

AsciiDoc reserves the following predefined, or Special, section names for specific purposes:

miscellaneous

Configuration options that don't belong anywhere else.

attributes

Named substitution values.

specialcharacters

Special characters reserved by the backend markup.

tags

Markup tag definitions used by AsciiDoc markup mechanisms.

quotes

Definitions for inline character formatting quoting.

specialwords

Lists of words and phrases singled out for special markup.

replacements

Find and replace substitution definitions.

specialsections

Used to single out section names for special markup.

macros

Macro syntax definitions. titles: Heading, section and block title parameters.

paradef*

Paragraph element definitions.

blockdef*

DelimitedBlock element definitions.

listdef*

List element definitions.

tabledef*

Table element definitions.

Each line of text in a Special section is a section entry. Section entries can take the following forms:

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).

Section entry behavior

• All equalo to the native roff man page format (or other formats).

  For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc directory was used to generate both asciidoc.1.css-embedded.html HTML file and (via the xmlto(1) command) the asciidoc.1 roff formatted asciidoc(1) man page.

  To find out more about man pages view the man(7) manpage (man 7 man command).

  Document Heading

  The document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

  The NAME Section

  The first manpage section is mandatory and must be called NAME and contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

  printf, fprintf, sprintf - print formatted output
  

  The SYNOPSIS Section

  The second manpage section is mandatory and must be called SYNOPSIS.

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 document and user specific configuration files.

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 hash character "#" are treated as comments and ignored.
• Same named sections and section entries override sections and section entries from previously loaded configuration files (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections or section entries that need to be overridden.
• Same named sections from different documents are merged automatically.

	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(1) program directory along with generated backend output and the backend markup spec. You view configuration file processing by turning on the asciidoc(1) -v command-line option.

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. A markup template section body can contain:

• Backend markup
• Attribute references
• A document content placeholder

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

Special Sections

AsciiDoc reserves the following predefined, or Special, section names for specific purposes:

miscellaneous

Configuration options that don't belong anywhere else.

attributes

Named substitution values.

specialcharacters

Special characters reserved by the backend markup.

tags

Markup tag definitions used by AsciiDoc markup mechanisms.

quotes

Definitions for inline character formatting quoting.

specialwords

Lists of words and phrases singled out for special markup.

replacements

Find and replace substitution definitions.

specialsections

Used to single out section names for special markup.

macros

Macro syntax definitions. titles: Heading, section and block title parameters.

paradef*

Paragraph element definitions.

blockdef*

DelimitedBlock element definitions.

listdef*

List element definitions.

tabledef*

Table element definitions.

Each line of text in a Special section is a section entry. Section entries can take the following forms:

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).

Section entry behavior

• All equalo to the native roff man page format (or other formats).

  For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc directory was used to generate both asciidoc.1.css-embedded.html HTML file and (via the xmlto(1) command) the asciidoc.1 roff formatted asciidoc(1) man page.

  To find out more about man pages view the man(7) manpage (man 7 man command).

  Document Heading

  The document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

  The NAME Section

  The first manpage section is mandatory and must be called NAME and contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

  printf, fprintf, sprintf - print formatted output
  

  The SYNOPSIS Section

  The second manpage section is mandatory and must be called SYNOPSIS.

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 document and user specific configuration files.

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 hash character "#" are treated as comments and ignored.
• Same named sections and section entries override sections and section entries from previously loaded configuration files (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections or section entries that need to be overridden.
• Same named sections from different documents are merged automatically.

	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(1) program directory along with generated backend output and the backend markup spec. You view configuration file processing by turning on the asciidoc(1) -v command-line option.

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. A markup template section body can contain:

• Backend markup
• Attribute references
• A document content placeholder

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

Special Sections

AsciiDoc reserves the following predefined, or Special, section names for specific purposes:

miscellaneous

Configuration options that don't belong anywhere else.

attributes

Named substitution values.

specialcharacters

Special characters reserved by the backend markup.

tags

Markup tag definitions used by AsciiDoc markup mechanisms.

quotes

Definitions for inline character formatting quoting.

specialwords

Lists of words and phrases singled out for special markup.

replacements

Find and replace substitution definitions.

specialsections

Used to single out section names for special markup.

macros

Macro syntax definitions. titles: Heading, section and block title parameters.

paradef*

Paragraph element definitions.

blockdef*

DelimitedBlock element definitions.

listdef*

List element definitions.

tabledef*

Table element definitions.

Each line of text in a Special section is a section entry. Section entries can take the following forms:

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).

Section entry behavior

• All equalo to the native roff man page format (or other formats).

  For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc directory was used to generate both asciidoc.1.css-embedded.html HTML file and (via the xmlto(1) command) the asciidoc.1 roff formatted asciidoc(1) man page.

  To find out more about man pages view the man(7) manpage (man 7 man command).

  Document Heading

  The document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

  The NAME Section

  The first manpage section is mandatory and must be called NAME and contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

  printf, fprintf, sprintf - print formatted output
  

  The SYNOPSIS Section

  The second manpage section is mandatory and must be called SYNOPSIS.

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 document and user specific configuration files.

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 hash character "#" are treated as comments and ignored.
• Same named sections and section entries override sections and section entries from previously loaded configuration files (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections or section entries that need to be overridden.
• Same named sections from different documents are merged automatically.

	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(1) program directory along with generated backend output and the backend markup spec. You view configuration file processing by turning on the asciidoc(1) -v command-line option.

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. A markup template section body can contain:

• Backend markup
• Attribute references
• A document content placeholder

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

Special Sections

AsciiDoc reserves the following predefined, or Special, section names for specific purposes:

miscellaneous

Configuration options that don't belong anywhere else.

attributes

Named substitution values.

specialcharacters

Special characters reserved by the backend markup.

tags

Markup tag definitions used by AsciiDoc markup mechanisms.

quotes

Definitions for inline character formatting quoting.

specialwords

Lists of words and phrases singled out for special markup.

replacements

Find and replace substitution definitions.

specialsections

Used to single out section names for special markup.

macros

Macro syntax definitions. titles: Heading, section and block title parameters.

paradef*

Paragraph element definitions.

blockdef*

DelimitedBlock element definitions.

listdef*

List element definitions.

tabledef*

Table element definitions.

Each line of text in a Special section is a section entry. Section entries can take the following forms:

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).

Section entry behavior

• All equalo to the native roff man page format (or other formats).

  For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc directory was used to generate both asciidoc.1.css-embedded.html HTML file and (via the xmlto(1) command) the asciidoc.1 roff formatted asciidoc(1) man page.

  To find out more about man pages view the man(7) manpage (man 7 man command).

  Document Heading

  The document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

  The NAME Section

  The first manpage section is mandatory and must be called NAME and contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

  printf, fprintf, sprintf - print formatted output
  

  The SYNOPSIS Section

  The second manpage section is mandatory and must be called SYNOPSIS.

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 document and user specific configuration files.

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 hash character "#" are treated as comments and ignored.
• Same named sections and section entries override sections and section entries from previously loaded configuration files (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections or section entries that need to be overridden.
• Same named sections from different documents are merged automatically.

	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(1) program directory along with generated backend output and the backend markup spec. You view configuration file processing by turning on the asciidoc(1) -v command-line option.

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. A markup template section body can contain:

• Backend markup
• Attribute references
• A document content placeholder

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

Special Sections

AsciiDoc reserves the following predefined, or Special, section names for specific purposes:

miscellaneous

Configuration options that don't belong anywhere else.

attributes

Named substitution values.

specialcharacters

Special characters reserved by the backend markup.

tags

Markup tag definitions used by AsciiDoc markup mechanisms.

quotes

Definitions for inline character formatting quoting.

specialwords

Lists of words and phrases singled out for special markup.

replacements

Find and replace substitution definitions.

specialsections

Used to single out section names for special markup.

macros

Macro syntax definitions. titles: Heading, section and block title parameters.

paradef*

Paragraph element definitions.

blockdef*

DelimitedBlock element definitions.

listdef*

List element definitions.

tabledef*

Table element definitions.

Each line of text in a Special section is a section entry. Section entries can take the following forms:

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).

Section entry behavior

• All equalo to the native roff man page format (or other formats).

  For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc directory was used to generate both asciidoc.1.css-embedded.html HTML file and (via the xmlto(1) command) the asciidoc.1 roff formatted asciidoc(1) man page.

  To find out more about man pages view the man(7) manpage (man 7 man command).

  Document Heading

  The document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

  The NAME Section

  The first manpage section is mandatory and must be called NAME and contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

  printf, fprintf, sprintf - print formatted output
  

  The SYNOPSIS Section

  The second manpage section is mandatory and must be called SYNOPSIS.

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 document and user specific configuration files.

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 hash character "#" are treated as comments and ignored.
• Same named sections and section entries override sections and section entries from previously loaded configuration files (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections or section entries that need to be overridden.
• Same named sections from different documents are merged automatically.

	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(1) program directory along with generated backend output and the backend markup spec. You view configuration file processing by turning on the asciidoc(1) -v command-line option.

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. A markup template section body can contain:

• Backend markup
• Attribute references
• A document content placeholder

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

Special Sections

AsciiDoc reserves the following predefined, or Special, section names for specific purposes:

miscellaneous

Configuration options that don't belong anywhere else.

attributes

Named substitution values.

specialcharacters

Special characters reserved by the backend markup.

tags

Markup tag definitions used by AsciiDoc markup mechanisms.

quotes

Definitions for inline character formatting quoting.

specialwords

Lists of words and phrases singled out for special markup.

replacements

Find and replace substitution definitions.

specialsections

Used to single out section names for special markup.

macros

Macro syntax definitions. titles: Heading, section and block title parameters.

paradef*

Paragraph element definitions.

blockdef*

DelimitedBlock element definitions.

listdef*

List element definitions.

tabledef*

Table element definitions.

Each line of text in a Special section is a section entry. Section entries can take the following forms:

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).

Section entry behavior

• All equalo to the native roff man page format (or other formats).

  For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc directory was used to generate both asciidoc.1.css-embedded.html HTML file and (via the xmlto(1) command) the asciidoc.1 roff formatted asciidoc(1) man page.

  To find out more about man pages view the man(7) manpage (man 7 man command).

  Document Heading

  The document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

  The NAME Section

  The first manpage section is mandatory and must be called NAME and contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

  printf, fprintf, sprintf - print formatted output
  

  The SYNOPSIS Section

  The second manpage section is mandatory and must be called SYNOPSIS.

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 document and user specific configuration files.

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 hash character "#" are treated as comments and ignored.
• Same named sections and section entries override sections and section entries from previously loaded configuration files (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections or section entries that need to be overridden.
• Same named sections from different documents are merged automatically.

	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(1) program directory along with generated backend output and the backend markup spec. You view configuration file processing by turning on the asciidoc(1) -v command-line option.

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. A markup template section body can contain:

• Backend markup
• Attribute references
• A document content placeholder

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

Special Sections

AsciiDoc reserves the following predefined, or Special, section names for specific purposes:

miscellaneous

Configuration options that don't belong anywhere else.

attributes

Named substitution values.

specialcharacters

Special characters reserved by the backend markup.

tags

Markup tag definitions used by AsciiDoc markup mechanisms.

quotes

Definitions for inline character formatting quoting.

specialwords

Lists of words and phrases singled out for special markup.

replacements

Find and replace substitution definitions.

specialsections

Used to single out section names for special markup.

macros

Macro syntax definitions. titles: Heading, section and block title parameters.

paradef*

Paragraph element definitions.

blockdef*

DelimitedBlock element definitions.

listdef*

List element definitions.

tabledef*

Table element definitions.

Each line of text in a Special section is a section entry. Section entries can take the following forms:

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).

Section entry behavior

• All equalo to the native roff man page format (or other formats).

  For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc directory was used to generate both asciidoc.1.css-embedded.html HTML file and (via the xmlto(1) command) the asciidoc.1 roff formatted asciidoc(1) man page.

  To find out more about man pages view the man(7) manpage (man 7 man command).

  Document Heading

  The document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

  The NAME Section

  The first manpage section is mandatory and must be called NAME and contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

  printf, fprintf, sprintf - print formatted output
  

  The SYNOPSIS Section

  The second manpage section is mandatory and must be called SYNOPSIS.

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 document and user specific configuration files.

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 hash character "#" are treated as comments and ignored.
• Same named sections and section entries override sections and section entries from previously loaded configuration files (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections or section entries that need to be overridden.
• Same named sections from different documents are merged automatically.

	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(1) program directory along with generated backend output and the backend markup spec. You view configuration file processing by turning on the asciidoc(1) -v command-line option.

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. A markup template section body can contain:

• Backend markup
• Attribute references
• A document content placeholder

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

Special Sections

AsciiDoc reserves the following predefined, or Special, section names for specific purposes:

miscellaneous

Configuration options that don't belong anywhere else.

attributes

Named substitution values.

specialcharacters

Special characters reserved by the backend markup.

tags

Markup tag definitions used by AsciiDoc markup mechanisms.

quotes

Definitions for inline character formatting quoting.

specialwords

Lists of words and phrases singled out for special markup.

replacements

Find and replace substitution definitions.

specialsections

Used to single out section names for special markup.

macros

Macro syntax definitions. titles: Heading, section and block title parameters.

paradef*

Paragraph element definitions.

blockdef*

DelimitedBlock element definitions.

listdef*

List element definitions.

tabledef*

Table element definitions.

Each line of text in a Special section is a section entry. Section entries can take the following forms:

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).

Section entry behavior

• All equalo to the native roff man page format (or other formats).

  For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc directory was used to generate both asciidoc.1.css-embedded.html HTML file and (via the xmlto(1) command) the asciidoc.1 roff formatted asciidoc(1) man page.

  To find out more about man pages view the man(7) manpage (man 7 man command).

  Document Heading

  The document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

  The NAME Section

  The first manpage section is mandatory and must be called NAME and contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

  printf, fprintf, sprintf - print formatted output
  

  The SYNOPSIS Section

  The second manpage section is mandatory and must be called SYNOPSIS.

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 document and user specific configuration files.

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 hash character "#" are treated as comments and ignored.
• Same named sections and section entries override sections and section entries from previously loaded configuration files (this is sometimes referred to as cascading). Consequently, downstream configuration files need only contain those sections or section entries that need to be overridden.
• Same named sections from different documents are merged automatically.

	Tip
	When creating custom configuration files you only need t