AsciiDoc cheatsheet

Abstract

This is a cheatsheet for AsciiDoc - “Text based document generation” script. The cheatsheet available for different AsciiDoc versions (because of some markup syntax changes) and using different css styles. Here is list with all available cheatsheets for different AsciiDoc version and using different css styles.

This cheatsheet is for AsciiDoc 8.5.1, using default css.

Document header (REQUIRED)

Main Header
===========
Optional Author Name <optional@author.email>
Optional version, optional date
:Author:    AlternativeWayToSetOptional Author Name
:Email:     <AlternativeWayToSetOptional@author.email>
:Date:      AlternativeWayToSetOptional date
:Revision:  AlternativeWayToSetOptional version

Attributes

There a lot of predefined attributes in AsciiDoc, plus you can add your own. To get attribute value use {attributename} syntax.

`Author is {author} Version is {revision}`	Author is Alex Efros Version is 2.2.0
`:My name: Alex Efros My name is {myname}`	My name is Alex Efros
`Line with bad attribute {qwe} will be deleted`	Line deleted
`Escaped: \{qwe} and +++{qwe}+++`	Escaped: {qwe} and {qwe}

Headers

`Level 1 ------- Level 2 ~~~~~~~ Level 3 ^^^^^^^ Level 4 +++++++`	Level 1 Level 2 Level 3 Level 4
`== Level 1 === Level 2 ==== Level 3 ===== Level 4`	Level 1 Level 2 Level 3 Level 4

Paragraphs

.Optional Title

Usual
paragraph.

Optional Title

Usual paragraph.

.Optional Title

 Literal paragraph.
  Must be indented.

Optional Title

Literal paragraph.
 Must be indented.

.Optional Title

[source,perl]
die 'connect: '.$dbh->errstr;

Not a code in next paragraph.

Optional Title

die 'connect: '.$dbh->errstr;

Not a code in next paragraph.

.Optional Title
NOTE: This is an example
      single-paragraph note.

Optional Title

This is an example single-paragraph note.

.Optional Title
[NOTE]
This is an example
single-paragraph note.

Optional Title

This is an example single-paragraph note.

TIP: Tip.

Tip.

IMPORTANT: Important.

Important.

WARNING: Warning.

Warning.

CAUTION: Caution.

Caution.

Blocks

.Optional Title
----
*Listing* Block

Use: code or file listings
----

Optional Title

*Listing* Block

Use: code or file listings

.Optional Title
[source,perl]
----
# *Source* block
# Use: highlight code listings
# (require `source-highlight`)
use DBI;
my $dbh = DBI->connect('...',$u,$p)
    or die "connect: $dbh->errstr";
----

Optional Title

# *Source* block
# Use: highlight code listings
# (require `source-highlight`)
use DBI;
my $dbh = DBI->connect('...',$u,$p)
    or die "connect: $dbh->errstr";

.Optional Title
****
*Sidebar* Block

Use: sidebar notes :)
****

Sidebar Block

Use: sidebar notes :)

.Optional Title
==========================
*Example* Block

Use: examples :)

Default caption "Example:"
can be changed using

 [caption="Custom: "]

before example block.
==========================

Example 1: Optional Title

Example Block

Use: examples :)

Default caption "Example:" can be changed using

[caption="Custom: "]

before example block.

.Optional Title
[NOTE]
===============================
*NOTE* Block

Use: multi-paragraph notes.
===============================

Optional Title

NOTE Block

Use: multi-paragraph notes.

////
*Comment* block

Use: hide comments
////

++++
*Passthrough* Block
<p>
Use: backend-specific markup like
<table border="1">
<tr><td>1<td>2
</table>
++++

*Passthrough* Block

Use: backend-specific markup like

 .Optional Title
 ....
 *Literal* Block

 Use: workaround when literal
 paragraph (indented) like
   1. First.
   2. Second.
 incorrectly processed as list.
 ....

Optional Title

*Literal* Block

Use: workaround when literal
paragraph (indented) like
  1. First.
  2. Second.
incorrectly processed as list.

.Optional Title
[quote, cite author, cite source]
____
*Quote* Block

Use: cite somebody
____

Optional Title

Quote Block

Use: cite somebody

cite source
— cite author

Text

`forced + line break`	forced line break
normal, _italic_, bold, +mono+. ``double quoted'', `single quoted'. normal, ^super^, ~sub~.	normal, italic, bold, `mono`. “double quoted”, ‘single quoted’. normal, ^super, _sub.
Command: `ls -al` +mono bold+ `passthru bold`	Command: `ls -al` `mono bold` `passthru bold`
`Path: '/some/filez.txt', '.b'`	Path: /some/filez.txt, .b
`[red]#red text# [,yellow]#on yellow# [,,2]#large# [red,yellow,2]all bold`	red text on yellow large all bold
`Chars: n__i__b++m++[red]##r##`	Chars: nib`m`r
`// Comment`
`(C) (R) (TM) -- ... -> <- => <= ¶`	© ® ™ — … → ← ⇒ ⇐ ¶
`''''`
Escaped: \_italic_, +++_italic_+++, t\__e__st, +++t__e__st+++, +++<b>bold</b>+++, $$<b>normal</b>$$ \¶ \`not single quoted' \`\`not double quoted''	Escaped: _italic_, _italic_, t__e__st, t__e__st, bold, <b>normal</b> ¶ `not single quoted' ``not double quoted''

Macros: links, images & include

If you’ll need to use space in url/path you should replace it with %20.

`[[anchor-1]] Paragraph or block 1. anchor:anchor-2[] Paragraph or block 2. <<anchor-1>>, <<anchor-1,First anchor>>, xref:anchor-2[], xref:anchor-2[Second anchor].`	Paragraph or block 1. Paragraph or block 2. [anchor-1], First anchor, [anchor-2], Second anchor.
`link:asciidoc[This document] link:asciidoc.html[] link:/index.html[This site root]`	This document asciidoc.html This site root
`http://google.com http://google.com[Google Search] mailto:root@localhost[email admin]`	http://google.com Google Search email admin
`First home image:images/icons/home.png[] , second home image:images/icons/home.png[Alt text] . .Block image image::images/icons/home.png[] image::images/icons/home.png[Alt text] .Thumbnail linked to full image image:/images/font/640-screen2.gif[ "My screenshot",width=128, link="/images/font/640-screen2.gif"]`	First home , second home . Figure 1: Block image Thumbnail linked to full image
`This is example how files can be included. It's commented because there no such files. :) // include::footer.txt[] // [perl] // source~~~~ // include::script.pl[] // source~~~~`	This is example how files can be included. It’s commented because there no such files. :)

Lists

.Bulleted
* bullet
* bullet
  - bullet
  - bullet
* bullet
** bullet
** bullet
*** bullet
*** bullet
**** bullet
**** bullet
***** bullet
***** bullet
**** bullet
*** bullet
** bullet
* bullet

Bulleted

bullet
bullet
- bullet
- bullet
bullet
- bullet
- bullet
  - bullet
  - bullet
    
    bullet
    
    bullet
    
    bullet
    
    bullet
    
    bullet
  - bullet
- bullet
bullet

.Bulleted 2
- bullet
  * bullet

Bulleted 2

bullet
- bullet

.Ordered
. number
. number
  .. letter
  .. letter
. number
.. loweralpha
.. loweralpha
... lowerroman
... lowerroman
.... upperalpha
.... upperalpha
..... upperroman
..... upperroman
.... upperalpha
... lowerroman
.. loweralpha
. number

Ordered

number
number
1. letter
2. letter
number
1. loweralpha
2. loweralpha
  1. lowerroman
  2. lowerroman
    
    upperalpha
    
    upperalpha
    
    upperroman
    
    upperroman
    
    upperalpha
  3. lowerroman
3. loweralpha
number

.Ordered 2
a. letter
b. letter
   .. letter2
   .. letter2
       .  number
       .  number
           1. number2
           2. number2
           3. number2
           4. number2
       .  number
   .. letter2
c. letter

Ordered 2

letter
letter
1. letter2
2. letter2
  1. number
  2. number
    
    number2
    
    number2
    
    number2
    
    number2
  3. number
3. letter2
letter

.Labeled
Term 1::
    Definition 1
Term 2::
    Definition 2
    Term 2.1;;
        Definition 2.1
    Term 2.2;;
        Definition 2.2
Term 3::
    Definition 3
Term 4:: Definition 4
Term 4.1::: Definition 4.1
Term 4.2::: Definition 4.2
Term 4.2.1:::: Definition 4.2.1
Term 4.2.2:::: Definition 4.2.2
Term 4.3::: Definition 4.3
Term 5:: Definition 5

Labeled

Term 1

Definition 1

Term 2

Definition 2

Term 2.1: Definition 2.1
Term 2.2: Definition 2.2

Term 3

Definition 3

Term 4

Definition 4

Term 4.1

Definition 4.1

Term 4.2

Definition 4.2

Term 4.2.1: Definition 4.2.1
Term 4.2.2: Definition 4.2.2

Term 4.3

Definition 4.3

Term 5

Definition 5

.Labeled 2
Term 1;;
    Definition 1
    Term 1.1::
        Definition .1.1

Labeled 2

Term 1

Definition 1

Term 1.1: Definition .1.1

[horizontal]
.Labeled horizontal
Term 1:: Definition 1
Term 2:: Definition 2
[horizontal]
    Term 2.1;;
        Definition 2.1
    Term 2.2;;
        Definition 2.2
Term 3::
    Definition 3
Term 4:: Definition 4
[horizontal]
Term 4.1::: Definition 4.1
Term 4.2::: Definition 4.2
[horizontal]
Term 4.2.1:::: Definition 4.2.1
Term 4.2.2:::: Definition 4.2.2
Term 4.3::: Definition 4.3
Term 5:: Definition 5

Labeled horizontal

Term 1

Definition 1

Term 2

Definition 2

Term 2.1	Definition 2.1
Term 2.2	Definition 2.2

Term 3

Definition 3

Term 4

Definition 4

Term 4.1

Definition 4.1

Term 4.2

Definition 4.2

Term 4.2.1	Definition 4.2.1
Term 4.2.2	Definition 4.2.2

Term 4.3

Definition 4.3

Term 5

Definition 5

[qanda]
.Q&A
Question 1::
    Answer 1
Question 2:: Answer 2

Q&A

Question 1

Answer 1
Question 2

Answer 2

.Indent is optional
- bullet
    * another bullet
        1. number
        .  again number
            a. letter
            .. again letter

.. letter
. number

* bullet
- bullet

Indent is optional

bullet
- another bullet
  1. number
    
    again number
    
    letter
    
    again letter
    
    letter
    
    number
- bullet
bullet

.Break two lists
. number
. number

Independent paragraph break list.

. number

.Header break list too
. number

--
. List block define list boundary too
. number
. number
--

--
. number
. number
--

Break two lists

number
number

Independent paragraph break list.

number

Header break list too

number

List block define list boundary too
number
number

number
number

.Continuation
- bullet
continuation
. number
  continuation
* bullet

  literal continuation

.. letter
+
Non-literal continuation.
+
----
any block can be

included in list
----
+
Last continuation.

Continuation

bullet continuation
1. number continuation
  - bullet
    
    literal continuation
    
    letter
    
    Non-literal continuation.
    
    any block can be included in list
    
    Last continuation.

.List block allow sublist inclusion
- bullet
  * bullet
+
--
    - bullet
      * bullet
--
  * bullet
- bullet
  . number
    .. letter
+
--
      . number
        .. letter
--
    .. letter
  . number

List block allow sublist inclusion

bullet
- bullet
  - bullet
  - bullet
- bullet
bullet
1. number
  1. letter
    
    number
    
    letter
  2. letter
2. number

Tables

You can fill table from CSV file using include:: macros inside table.

.An example table
[options="header,footer"]
|=======================
|Col 1|Col 2      |Col 3
|1    |Item 1     |a
|2    |Item 2     |b
|3    |Item 3     |c
|6    |Three items|d
|=======================

Table 1: An example table
Col 1	Col 2	Col 3
6	Three items	d
1	Item 1	a
2	Item 2	b
3	Item 3	c

.CSV data, 15% each column
[format="csv",width="60%",cols="4"]
[frame="topbot",grid="none"]
|======
1,2,3,4
a,b,c,d
A,B,C,D
|======

Table 2: CSV data, 15% each column
1	2	3	4
a	b	c	d
A	B	C	D

[grid="rows",format="csv"]
[options="header",cols="^,<,<s,<,>m"]
|===========================
ID,FName,LName,Address,Phone
1,Vasya,Pupkin,London,+123
2,X,Y,"A,B",45678
|===========================

ID	FName	LName	Address	Phone
1	Vasya	Pupkin	London	`+123`
2	X	Y	A,B	`45678`

.Multiline cells, row/col span
|====
|Date |Duration |Avg HR |Notes

|22-Aug-08 .2+^.^|10:24 | 157 |
Worked out MSHR (max sustainable
heart rate) by going hard
for this interval.

|22-Aug-08 | 152 |
Back-to-back with previous interval.

|24-Aug-08 3+^|none

|====

Table 3: Multiline cells, row/col span
Date	Duration	Avg HR	Notes
22-Aug-08	10:24	157	Worked out MSHR (max sustainable heart rate) by going hard for this interval.
22-Aug-08	10:24	152	Back-to-back with previous interval.
24-Aug-08	none

AsciiDoc cheatsheet

Abstract

Document header (REQUIRED)

Attributes

Headers

Level 1

Level 2

Level 3

Level 4

Level 1

Level 2

Level 3

Level 4

Paragraphs

Blocks

Text

Macros: links, images & include

Lists

Tables