AsciiDoc Markup Syntax Quick Summary

A summary of the most often used markup. For a complete reference see the AsciiDoc User Guide.

Text formatting

'emphasized text'           (normally italics)
*bold text*                 (boldface font)
`monospaced text`           (proportional font)

emphasized text (normally italics) bold text (boldface font) monospaced text (proportional font)

Document header

The Document Title
==================
author <email>            (optional)
revision, date            (optional)

Section title underlines

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

One line titles

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

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

Section title (level 2)

Section title (level 3)

Section title (level 4)

= Document Title (level 0)
ERROR: only book doctypes can contain level 0 sections

Paragraphs

Default Paragraph, Literal Paragraph, & Admonition Paragraphs

Default Paragraph

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.

The verse paragraph style is useful for lyrics and poems. For example:

[verse]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

Renders:

Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui.

Literal Paragraph

A Literal paragraph ([paradef-literal]) consists of one or more lines of text, where the first line is indented by one or more 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.

  Note that only the first line need to be indented. I.e., the whole
paragraph will be considered a Literal Paragraph if merely the first
line is indented, like this paragraph.

Admonition Paragraphs

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.

or the alternative syntax:

[NOTE]
This is an example note.

Renders:

This is an example note.

Admonition accept only single paragraphs.

If your admonition is more than a single paragraph use an admonition block instead.

Comment Lines

Single lines starting with two forward slashes hard up against the left margin are treated as comments and are stripped from the output. Comment lines have been implemented as a block macro and are only valid in a block context — they are not treated as comments inside paragraphs or delimited blocks. Example comment line:

// This is a comment.

Delimited blocks

Predefined delimited block underlines:

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

Table: Default DelimitedBlock substitutions
	Backend	Listing	Literal	Sidebar	Quote
Callouts	No	Yes	Yes	No	No
Attributes	Yes	No	No	Yes	Yes
Inline Macros	Yes	No	No	Yes	Yes
Quotes	No	No	No	Yes	Yes
Replacements	No	No	No	Yes	Yes
Special chars	No	Yes	Yes	Yes	Yes
Special words	No	No	No	Yes	Yes

Delimiters must begin at left margin.

-------------------
listing block
-------------------

listing block

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.

...................
literal block
...................

literal block

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

1. Item 1
2. Item 2

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

*******************
sidebar block
*******************

sidebar block

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.

[author, source]            (optional)
___________________
quote block
___________________

quote block

source
— author

A good notation has subtlety and suggestiveness which at times makes it almost seem like a live teacher.

The World of Mathematics (1956)
— Bertrand Russell

///////////////////
comment block
///////////////////

Admonition Blocks

The ExampleBlock definition includes a set of admonition styles (NOTE, TIP, IMPORTANT, WARNING, CAUTION) for generating admonition blocks (admonitions containing more than just a simple paragraph). Just precede the ExampleBlock with an attribute list containing the admonition style name. For example:

[NOTE]
.A 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.
=====================================================================

[IMPORTANT]
=====================================================================
This block is very important.

This block is very important.
=====================================================================

Renders:

A NOTE block

Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens.

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

This block is very important.

More block elements

[attributes list]           (Note 1)
.Block title                (Note 1)
// Comment line             (Note 1)
include::filename[]         (Note 1)

Note 1: Begin at the left margin.

BlockTitles

A BlockTitle element is a single line beginning with a period followed by a title. The title is applied to the next Paragraph, DelimitedBlock, List, Table or BlockMacro. For example:

.Notes
- Note 1.
- Note 2.

is rendered as:

Notes

Note 1.
Note 2.

BlockId Element

A BlockId is a single line block element containing a unique identifier enclosed in double square brackets. It is used to assign an identifier to the ensuing block element for use by referring links. For example:

[[chapter-titles]]
Chapter titles can be ...

Chapter titles can be …

The preceding example identifies the following paragraph so it can be linked from other location, for example with <<chapter-titles,chapter titles>> chapter titles.

BlockId elements can be applied to Title, Paragraph, List, DelimitedBlock, Table and BlockMacro elements. The BlockId element is really just an AttributeList with a special syntax which sets the {id} attribute for substitution in the subsequent block's markup template.

The BlockId element has the same syntax and serves a similar function to the anchor inline macro.

More inline elements

footnote:[footnote text]    (document footnote)

Document links

[[id]]                      (define link target)
<<id,caption>>              (link to target id)
link:filename#id[caption]   (link to external HTML file)

URLs

http:address[caption]       (link to web page)
mailto:address[caption]     (link to mail recipient)

Images

image:filename[caption]     (inline image)
image::filename[caption]    (block image)

AsciiDoc Advanced Syntax.

Text Formatting

Text Formatting.

Superscripts and Subscripts

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.

Line Breaks (HTML/XHTML)

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.

emphasized text (normally italics) bold text (boldface font) monospaced text (proportional font)

Rulers (HTML/XHTML)

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

List types

Bulleted lists. Also known as itemized or unordered lists.
Numbered lists. Also called ordered lists.
Labeled lists. Sometimes called variable or definition lists.
Callout lists (a list of callout annotations).

List behavior

Indentation is optional and does not determine nesting, indentation does however make the source more readable.
A nested list must use a different syntax from its parent so that asciidoc(1) can distinguish the start of a nested list.
By default lists of the same type can only be nested two deep; this could be increased by defining new list definitions.
In addition to nested lists a list item will include immediately following Literal paragraphs.
Use List Item Continuation to include other block elements in a list item.

Bulleted and Numbered Lists

Bulleted list items start with a dash or an asterisk 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.

.Spaced List Example
- Praesent 1.

  * Vivamus fringilla mi eu lacus.

    - Fusce euismod - *same type can not be used again in sub lists*

  * Donec eget arcu bibendum nunc consequat lobortis.
    - Fusce euismod commodo velit.

- Praesent 2.

  . Fusce euismod commodo velit.

    .. Fusce euismod commodo velit.

    .. Vivamus fringilla mi eu lacus.

    .. Donec eget arcu bibendum nunc consequat lobortis.

  . Vivamus fringilla mi eu lacus.
+
  title KNOPPIX
        root   (hd0,0)
        kernel /boot.knoppix/isolinux/linux 2 fromhd=/dev/hda4 lang=us
        initrd /boot.knoppix/isolinux/minirt.gz
+
notice the fromhd parameter: it's the location of the /KNOPPIX directory.

  . Donec eget arcu bibendum nunc consequat lobortis.

  . Nam fermentum mattis ante.

Which render as:

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.
1. Fusce euismod commodo velit.
2. Vivamus fringilla mi eu lacus.
  1. Fusce euismod commodo velit.
  2. Vivamus fringilla mi eu lacus.
3. Donec eget arcu bibendum nunc consequat lobortis.
Praesent eget purus quis magna eleifend eleifend.
1. Fusce euismod commodo velit.
  1. Fusce euismod commodo velit.
  2. Vivamus fringilla mi eu lacus.
  3. 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.

Spaced List Example

Praesent 1.
- Vivamus fringilla mi eu lacus.
Fusce euismod - same type can not be used again in sub lists
- Donec eget arcu bibendum nunc consequat lobortis.
Fusce euismod commodo velit.
Praesent 2.
1. Fusce euismod commodo velit.
  1. Fusce euismod commodo velit.
  2. Vivamus fringilla mi eu lacus.
  3. Donec eget arcu bibendum nunc consequat lobortis.
2. Vivamus fringilla mi eu lacus.
```
title KNOPPIX
      root   (hd0,0)
      kernel /boot.knoppix/isolinux/linux 2 fromhd=/dev/hda4 lang=us
      initrd /boot.knoppix/isolinux/minirt.gz
```
  notice the fromhd parameter: it's the location of the /KNOPPIX directory.
3. Donec eget arcu bibendum nunc consequat lobortis.
4. Nam fermentum mattis ante.

List Item Continuation

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 list continuation 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:

List item one.

List item one continued with a second paragraph followed by a Listing block.
```
$ ls *.sh
$ mv *.sh ~/tmp
```
List item one continued with a third paragraph.

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.

List Block

A List block is a special delimited block containing a list element.

All elements between in the List Block are part of the preceding list item. In this respect the List block behaves like List Item Continuation except that list items contained within the block do not require explicit + list item continuation lines:
The block delimiter is a single line containing two dashes.
Any block title or attributes are passed to the first element inside the block.

The List Block is useful for:

Lists with long multi-element list items.
Nesting a list within a parent list item (by default nested lists follow the preceding list item).

Here's an example of a nested list block:

.Nested List Block
1. List item one.
+
This paragraph is part of the preceding list item
+
--
a. This list is nested and does not require explicit item continuation.

This paragraph is part of the preceding list item

b. List item b.

This paragraph belongs to list item b.
--
+
This paragraph belongs to item 1.

1. dupe of list item one.
+
--

Then followed by,

a bunch or two parargraphs.

Or maybe more.

Note that the preceding + is vitally imporant. Check with next example.
--

2. Item 2 of the outer list.
--
Then followed by,

a bunch or two parargraphs.

Or maybe more.
--
3. Item 3 of the outer list.

Renders:

Nested List Block

List item one.

This paragraph is part of the preceding list item
1. This list is nested and does not require explicit item continuation.
  
  This paragraph is part of the preceding list item
2. List item b.
  
  This paragraph belongs to list item b.
This paragraph belongs to item 1.
dupe of list item one.

Then followed by,

a bunch or two parargraphs.

Or maybe more.

Note that the preceding + is vitally imporant. Check with next example.
Item 2 of the outer list.

Then followed by,

a bunch or two parargraphs.

Or maybe more.

Item 3 of the outer list.

Vertical Labeled Lists

Tags: html definitions

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.
+
  Fusce euismod commodo velit.

Lorem::
+
--

Fusce euismod commodo velit.

Fusce euismod commodo velit.

  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.

. why this is still with last item?

. and this?

Lorem::
  Fusce euismod commodo velit.

Where would this parargraph be?

Lorem::
  Fusce euismod commodo velit.

. how about this?

Which render as:

Lorem

Fusce euismod commodo velit.

Fusce euismod commodo velit.

Lorem

Fusce euismod commodo velit.

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.

why this is still with last item?
and this?

Lorem

Fusce euismod commodo velit.

Where would this parargraph be?

Lorem

Fusce euismod commodo velit.

how about this?

Horizontal Labeled Lists

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.

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.

Which render as:

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.

Use vertical labeled lists in preference to horizontal labeled lists — current PDF toolchains do not make a good job of determining the relative column widths.
If you are generating DocBook markup the horizontal labeled lists should be nested because the DocBook XML V4.2 DTD does not permit nested informal tables (although DocBook XSL Stylesheets process them correctly).

Question and Answer Lists

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

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

Renders:

Question one

Answer one.
Question two

Answer two.

Glossary Lists

AsciiDoc comes pre-configured with a labeled list (:- label delimiter) for generating DocBook 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.

To generate valid DocBook output glossary lists must be located in a glossary section.

Bibliography Lists

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

Tables are the most complex AsciiDoc elements and this section is quite long.
[The current table syntax is overly complicated and unwieldy to edit, hopefully a more usable syntax will appear in future versions of AsciiDoc.]

AsciiDoc generates nice HTML tables, but the current crop of DocBook toolchains render tables with varying degrees of success. Use tables only when really necessary.

Example Tables

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:

Backtick (`) — align left.
Single quote (') — align right.
Period (.) — align center.

Simple table:

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

Output:

1	2
3	4
5	6

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:

Table: An example table
Column 1	Column 2
6	Three items
1	Item 1
2	Item 2
3	Item 3

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

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

````~
1,2,3,4
a,b,c,d
A,B,C,D
~~~~~~~~

````~
1,2,3,4
a,b,c,d
A,B,C,D
short,a bit longer, much longer than 1st, "Oh dear, this one is extreme long"
~~~~~~~~

`10`15`25`~
1,2,3,4
a,b,c,d
A,B,C,D
~~~~~~~~

`5`10`15`25~40
1,2,3,4
a,b,c,d
A,B,C,D
~~~~~~~~

Output:

1	2	3	4
a	b	c	d
A	B	C	D

1	2	3	4
a	b	c	d
A	B	C	D

1	2	3	4
a	b	c	d
A	B	C	D
short	a bit longer	much longer than 1st	Oh dear, this one is extreme long

1	2	3	4
a	b	c	d
A	B	C	D

1	2	3	4
a	b	c	d
A	B	C	D

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[]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Text based multi-row tables are not grouped as you wished, but the generated table does not look bad either.

 `----------`-----------------------------`-------------------------------
 Key        Arguments                     Event
            to callback
 ------------------------------------------------------------------------
 Final      parser handle                 Document parsing completed

 Start      parser handle,                Start tag found
            element name,
            attributes

 End        parser handle,                End tag found
            element name
 ------------------------------------------------------------------------

Key	Arguments	Event
	to callback
Final	parser handle	Document parsing completed

Start	parser handle,	Start tag found
	element name,
	attributes

End	parser handle,	End tag found
	element name

Macros are a mechanism for substituting parameterized text into output documents.

Macros have a name, a single target argument and an attribute list. The default syntax is <name>:<target>[<attributelist>] (for inline macros) and <name>::<target>[<attributelist>] (for block macros). Here are some examples:

http://www.methods.co.nz/asciidoc/index.html[Asciidoc home page]
include::chapt1.txt[tabsize=2]
mailto:srackham@methods.co.nz[]

Inline Macros

Inline Macros occur in an inline element context. Predefined Inline macros include URLs, 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 caption text is provided the URL itself is displayed.

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

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

Internal Cross References

Two AsciiDoc inline macros are provided for creating hypertext links within an AsciiDoc document. You can use either the standard macro syntax or the (preferred) alternative.

anchor

Used to specify hypertext link targets:

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

The <id> is a unique identifier that must begin with a letter. The optional <xreflabel> is the text to be displayed by captionless xref macros that refer to this anchor. The optional <xreflabel> is only really useful when generating DocBook output. Example anchor:

[[X1]]

You may have noticed that the syntax of this inline element is the same as that of the BlockId block element, this is no coincidence since they are functionally equivalent.

xref

Creates a hypertext link to a document anchor.

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

The <id> refers to an existing anchor <id>. The optional <caption> is the link's displayed text. If <caption> is not specified then the <id>, enclosed in square brackets, is displayed. Example:

<<X15,attribute lists>>

Linking to Local Documents

Hypertext links to files on the local filesystem are specified using the link inline macro.

link:<target>[<caption>]

The link macro generates relative URLs. The link macro <target> is the target file name (relative to the file system location of the referring document). The optional <caption> is the link's displayed text. If <caption> is not specified then <target> is displayed. Example:

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

You can use the <filename>#<id> syntax to refer to an anchor within a target document but this usually only makes sense when targeting HTML documents.

Images can serve as hyperlinks using the image macro.

Images

Inline images are inserted into the output document using the image macro. The inline syntax is:

image:<target>[<attributes>]

The contents of the image file <target> is displayed. To display the image it's file format must be supported by the target backend application. HTML and DocBook applications normally support PNG or JPG files.

<target> file name paths are relative to the location of the referring document.

Image macro attributes

The optional first positional attribute list entry specifies the alternative text which is displayed if the output application is unable to process the image file. For example:
```
image:images/logo.png[Company Logo]
```
The optional width and height named attributes scale the image size and can be used in any combination. The following example scales the previous example to a height of 32 pixels:
```
image:images/logo.png["Company Logo",height=32]
```
The optional link named attribute is used to link the image to an external document. The following example links a screenshot thumbnail to a full size version:
```
image:screen-thumbnail.png[height=32,link="screen.png"]
```

Include Macros

These system macros include the contents of a named file in the source document; it's as if the included file were part of the parent document.

There are two include macros: include which allows nested include macros and include1 which does not allow nested includes.

Example: Include macro examples

 include::chapter1.txt[tabsize=4]

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

chapter1.txt is processed exactly as if its text were part of the parent document except that tabs are expanded to 4 characters.
Since it is enclosed in a BackendBlock the text from table6.html is included and written to the output without any further processing.

Filters are external shell commands used to process Paragraph and DelimitedBlock content; they are specified in configuration file Paragraph and DelimitedBlock definitions.

There's nothing special about the filters, they're just standard UNIX filters: they read text from the standard input, process it, and write it to the standard output.

Attribute substitution is performed on the filter command prior to execution — attributes can be used to pass parameters from the AsciiDoc source document to the filter.

Filters can potentially generate unsafe output. Before installing a filter you should verify that it can't be coerced into generating malicious output or exposing sensitive information.

Filter functionality is currently only available on POSIX platforms (this includes Cygwin).

Filter Search Paths

If the filter command does not specify a directory path then asciidoc(1) searches for the command:

First it looks in the user's $HOME/.asciidoc/filters directory.
Next the /etc/asciidoc/filters directory is searched.
Then it looks in the asciidoc(1) ./filters directory.
Finally it relies on the executing shell to search the environment search path ($PATH).

Filter Configuration Files

Since filters are normally accompanied by a configuration file containing an example filter Paragraph or filter DelimitedBlock definition.

asciidoc(1) auto-loads all .conf files found in the user's $HOME/.asciidoc/filters directory and the asciidoc(1) ./filters subdirectory.

Code Filter

AsciiDoc comes with a simple minded code-filter for highlighting source code keywords and comments. You'll find this example in the AsciiDoc distribution ./filters subdirectory (read the ./filters/code-filter-readme.txt file for instructions).

A full featured source code highlighter filter (source-highlight-filter.conf) using GNU source-highlight can be found in the AsciiDoc distribution ./examples/source-highlight-filter directory. GNU source-highlight generates nicely formatted source code for most common programming languages.

Example: Shell source file source-highlight-filter example

#!/bin/bash
#
# rc file for automount using a Sun-style "master map".
# We first look for a local /etc/auto.master, then a YP
# map with that name
#

FLAGS="defaults 21"
DAEMON=/usr/sbin/automount
prog=`basename $DAEMON`
initdir=/etc/init.d