Asciidoc markup

Text formatting

Description Syntax Result Remark

Description	Syntax	Result	Remark
Emphasis, quotes	`One 'Two' Three`	One 'Two' Three
Emphasis, underscores	`One Two Three`	One Two Three
Emphasis, quotes, unconstrained	`One''Two''Three`	One''Two''Three
Emphasis, underscores, unconstrained	`OneTwoThree`	OneTwoThree
Strong	`One Two Three`	One Two Three
Strong, unconstrained	`OneTwoThree`	OneTwoThree
Monospace	`One Two Three`	One Two Three
Monospace, unconstrained	`OneTwoThree`	OneTwoThree
Single quote	One `Two´ Three	One `Two´ Three	Doesn’t seem to work
Double quotes	One ``Two´´ Three	One ``Two´´ Three	Doesn’t seem to work
Single quote, unconstrained	One``Two´´Three	One``Two´´Three	Doesn’t seem to work
Unquoted	`One Two Three`	One Two Three	Meant to add inline attributes (see next line)
Colored text	`One Two Three`	One Two Three
Colored background	`One Two Three`	One Two Three
Big text	`One Two Three`	One Two Three
Underlined text	`One Two Three`	One Two Three
Overlined text	`One Two Three`	One Two Three
Line-through text	`One Two Three`	One Two Three
Combinations	`One Two Three`	One Two Three
Combinations, unconstrained	`OneTwoThree`	OneTwoThree
Big text	`One Two Three`	One Two Three
Superscript	`One ^Two Three`	One ^Two Three
More superscript	`One^TwoThree`	One^TwoThree
Subscript	`One _Two Three`	One _Two Three
More subscript	`One_TwoThree`	One_TwoThree

Emphasis, quotes

One 'Two' Three

One 'Two' Three

Emphasis, underscores

One Two Three

One Two Three

Emphasis, quotes, unconstrained

One''Two''Three

One''Two''Three

Emphasis, underscores, unconstrained

OneTwoThree

OneTwoThree

Strong

One Two Three

One Two Three

Strong, unconstrained

OneTwoThree

OneTwoThree

Monospace

One Two Three

One Two Three

Monospace, unconstrained

OneTwoThree

OneTwoThree

Single quote

One `Two´ Three

Doesn’t seem to work

Double quotes

One ``Two´´ Three

Doesn’t seem to work

Single quote, unconstrained

One``Two´´Three

Doesn’t seem to work

Unquoted

One Two Three

One Two Three

Meant to add inline attributes (see next line)

Colored text

One Two Three

One Two Three

Colored background

One Two Three

One Two Three

Big text

One Two Three

One Two Three

Underlined text

One Two Three

One Two Three

Overlined text

One Two Three

One Two Three

Line-through text

One Two Three

One Two Three

Combinations

One Two Three

One Two Three

Combinations, unconstrained

OneTwoThree

OneTwoThree

Big text

One Two Three

One Two Three

Superscript

One ^Two Three

One ^Two Three

More superscript

One^TwoThree

One^TwoThree

Subscript

One _Two Three

One _Two Three

More subscript

One_TwoThree

One_TwoThree

Paragraphs

General syntax:

[<STYLE>]
Some text. Not broken by
blank lines.

Valid styles are: literal, verse, quote, listing, TIP, NOTE, IMPORTANT, WARNING, CAUTION, abstract, partintro, comment, example, sidebar, source, music, latex, graphviz

Examples:

Normal paragraphs

Code:

How do you achieve a good balance between the test and control group? One good way is to 'randomize' the subjects. You can do this by randomly assigning all the subjects to one group or the other, or by first stratifying them into similar subsets, and then randomly assigning members from each subset into the test and control groups. It wouldn't do for the experimenter to assign subjects to one group or the other after having met the subjects; the experimenter might (consciously or unconsciously) assign healthier patients to one group.

In some cases, you can assign all subjects to both groups: in psychology experiments that measure things like reaction time, you can every subject try every experimental condition (in randomized order), because there is little or no influence between each trial. Obviously, you can't have subjects try every possibility on things like cardiac operations: you can only choose one option for each subject.

Result:

How do you achieve a good balance between the test and control group? One good way is to 'randomize' the subjects. You can do this by randomly assigning all the subjects to one group or the other, or by first stratifying them into similar subsets, and then randomly assigning members from each subset into the test and control groups. It wouldn’t do for the experimenter to assign subjects to one group or the other after having met the subjects; the experimenter might (consciously or unconsciously) assign healthier patients to one group.

In some cases, you can assign all subjects to both groups: in psychology experiments that measure things like reaction time, you can every subject try every experimental condition (in randomized order), because there is little or no influence between each trial. Obviously, you can’t have subjects try every possibility on things like cardiac operations: you can only choose one option for each subject.

Literal paragraphs

Prefix with one or more spaces

Code:

 How do you achieve a good balance between the test and control group? One good way is to 'randomize' the subjects. You can do this by randomly assigning all the subjects to one group or the other, or by first stratifying them into similar subsets, and then randomly assigning members from each subset into the test and control groups. It wouldn't do for the experimenter to assign subjects to one group or the other after having met the subjects; the experimenter might (consciously or unconsciously) assign healthier patients to one group.

 In some cases, you can assign all subjects to both groups: in psychology experiments that measure things like reaction time, you can every subject try every experimental condition (in randomized order), because there is little or no influence between each trial. Obviously, you can't have subjects try every possibility on things like cardiac operations: you can only choose one option for each subject.

Result:

How do you achieve a good balance between the test and control group? One good way is to 'randomize' the subjects. You can do this by randomly assigning all the subjects to one group or the other, or by first stratifying them into similar subsets, and then randomly assigning members from each subset into the test and control groups. It wouldn't do for the experimenter to assign subjects to one group or the other after having met the subjects; the experimenter might (consciously or unconsciously) assign healthier patients to one group.

In some cases, you can assign all subjects to both groups: in psychology experiments that measure things like reaction time, you can every subject try every experimental condition (in randomized order), because there is little or no influence between each trial. Obviously, you can't have subjects try every possibility on things like cardiac operations: you can only choose one option for each subject.

Add literal style

Code:

[literal]
How do you achieve a good balance between the test and control group? One good way is to 'randomize' the subjects. You can do this by randomly assigning all the subjects to one group or the other, or by first stratifying them into similar subsets, and then randomly assigning members from each subset into the test and control groups. It wouldn't do for the experimenter to assign subjects to one group or the other after having met the subjects; the experimenter might (consciously or unconsciously) assign healthier patients to one group.

[literal]
In some cases, you can assign all subjects to both groups: in psychology experiments that measure things like reaction time, you can every subject try every experimental condition (in randomized order), because there is little or no influence between each trial. Obviously, you can't have subjects try every possibility on things like cardiac operations: you can only choose one option for each subject.

Result:

How do you achieve a good balance between the test and control group? One good way is to 'randomize' the subjects. You can do this by randomly assigning all the subjects to one group or the other, or by first stratifying them into similar subsets, and then randomly assigning members from each subset into the test and control groups. It wouldn't do for the experimenter to assign subjects to one group or the other after having met the subjects; the experimenter might (consciously or unconsciously) assign healthier patients to one group.

In some cases, you can assign all subjects to both groups: in psychology experiments that measure things like reaction time, you can every subject try every experimental condition (in randomized order), because there is little or no influence between each trial. Obviously, you can't have subjects try every possibility on things like cardiac operations: you can only choose one option for each subject.

Verse paragraphs

Code:

[verse, William Blake, from Auguries of Innocence]
To see a world in a grain of sand,
And a heaven in a wild flower,
Hold infinity in the palm of your hand,
And eternity in an hour.

Result:

To see a world in a grain of sand,
And a heaven in a wild flower,
Hold infinity in the palm of your hand,
And eternity in an hour.

— William Blake
from Auguries of Innocence

Quote paragraphs

Code:

[quote, 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.

Result:

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

— Bertrand Russell
The World of Mathematics (1956)

Admonition paragraphs

Use prefix

Code:

NOTE: Mind the gap

TIP: Mind the gap

IMPORTANT: Mind the gap

WARNING: Mind the gap

CAUTION: Mind the gap

Result:

Note	Mind the gap

Tip	Mind the gap

Important

Mind the gap

Warning

Mind the gap

Caution

Mind the gap

Add style

Code:

[NOTE]
Mind the gap

[TIP]
Mind the gap

[IMPORTANT]
Mind the gap

[WARNING]
Mind the gap

[CAUTION]
Mind the gap

Result:

Note	Mind the gap

Tip	Mind the gap

Important

Mind the gap

Warning

Mind the gap

Caution

Mind the gap

Open blocks

General syntax:

[<STYLE>]
--
...
--

Valid styles : literal, verse, quote, listing, TIP, NOTE, IMPORTANT, WARNING, CAUTION, abstract, partintro, comment, example, sidebar, source, music, latex, graphviz

Examples:

Listing

Code:

[listing]
--
#include <stdio.h>

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

Result:

#include <stdio.h>

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

Literal

Code:

[listing]
--
How do you achieve a good balance between the test and control group? One good way is to 'randomize' the subjects. You can do this by randomly assigning all the subjects to one group or the other, or by first stratifying them into similar subsets, and then randomly assigning members from each subset into the test and control groups. It wouldn't do for the experimenter to assign subjects to one group or the other after having met the subjects; the experimenter might (consciously or unconsciously) assign healthier patients to one group.
--

Result:

How do you achieve a good balance between the test and control group? One good way is to 'randomize' the subjects. You can do this by randomly assigning all the subjects to one group or the other, or by first stratifying them into similar subsets, and then randomly assigning members from each subset into the test and control groups. It wouldn't do for the experimenter to assign subjects to one group or the other after having met the subjects; the experimenter might (consciously or unconsciously) assign healthier patients to one group.

Lists

Bulleted lists

Code:

- Top level item
* Sublevel
* Sublevel
** Subsublevel
*** And deeper
**** Four asterisks
***** Up to five
*** Level 3
** Subsublevel
- Top level item

Result:

Top level item
- Sublevel
- Sublevel
  - Subsublevel
    
    And deeper
    
    Four asterisks
    
    Up to five
    
    Level 3
  - Subsublevel
Top level item

Numbered lists

Explicit numbering

Code:

1.   Arabic (decimal) numbered list item.
a.   Lower case alpha (letter) numbered list item.
b.   Lower case alpha (letter) numbered list item.
A.   Upper case alpha (letter) numbered list item.
B.   Upper case alpha (letter) numbered list item.
C.   Upper case alpha (letter) numbered list item.
i) Lower case roman numbered list item.
ii) Lower case roman numbered list item.
iii) Lower case roman numbered list item.
iv) Lower case roman numbered list item.
I)  Upper case roman numbered list item.

Result:

Arabic (decimal) numbered list item.
1. Lower case alpha (letter) numbered list item.
2. Lower case alpha (letter) numbered list item.
  1. Upper case alpha (letter) numbered list item.
  2. Upper case alpha (letter) numbered list item.
  3. Upper case alpha (letter) numbered list item.
    
    Lower case roman numbered list item.
    
    Lower case roman numbered list item.
    
    Lower case roman numbered list item.
    
    Lower case roman numbered list item.
    
    Upper case roman numbered list item.

Implicit numbering

Code:

. Arabic (decimal) numbered list item.
.. Lower case alpha (letter) numbered list item.
... Lower case roman numbered list item.
.... Upper case alpha (letter) numbered list item.
..... Upper case roman numbered list item.

Result:

Arabic (decimal) numbered list item.
1. Lower case alpha (letter) numbered list item.
  1. Lower case roman numbered list item.
    
    Upper case alpha (letter) numbered list item.
    
    Upper case roman numbered list item.

Mixing styles

Also using style attributes.

Code:

- Top level bullets
* Second level bullets
* Second level bullets
[upperroman]
.. Third level: uppercase roman numerals
.. Third level: uppercase roman numerals
[arabic]
... Level 4: Arabic numerals
... Level 4: Arabic numerals

Result:

Top level bullets
- Second level bullets
- Second level bullets
  1. Third level: uppercase roman numerals
  2. Third level: uppercase roman numerals
    
    Level 4: Arabic numerals
    
    Level 4: Arabic numerals

Labeled Lists

Code:

*Canada*::
Item text can consist of several paragraphs.
Second line of first paragraph.

Second paragraph is not auto-indented however.


*USA*::
First paragraph.

  Second one. Indented in source code. It becomes "literal".

    California::: In source, text can be on same line as label.
    Texas:::
        Houston;;
        Dallas;; Item text is needed to end this list.

Result:

Canada: Item text can consist of several paragraphs. Second line of first paragraph.

Second paragraph is not auto-indented however.

USA

First paragraph.

Second one. Indented in source code. It becomes "literal".

California

In source, text can be on same line as label.

Texas

Houston
Dallas: Item text is needed to end this list.

Horizontal labeled Lists

Code:

[horizontal]
*Canada*:: Item text.

  Indented second paragraph.
*USA*:: Item text.

Result:

Canada	Item text.
USA	Item text.

Questions & Answers

Question one

Answer one.
Question two

Answer two.

Glossary

Glossary entries are an example of a style of AsciiDoc labeled lists.

Code:

[glossary]
A glossary term::
  The corresponding (indented) definition.

A second glossary term::
  The corresponding (indented) definition.

Result:

A glossary term: The corresponding (indented) definition.
A second glossary term: The corresponding (indented) definition.

Bibliography

Code:

[bibliography]
.Books
- [[[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.

[bibliography]
.Articles
- [[[abc2003]]] Gall Anonim. 'An article', Whatever. 2003.

Links to bibliography entries:

Please read <<taoup>>.

For a guide on DcoBook, see: <<walsh-muellner>>

This idea was first introduced in <<abc2003>>

Result:

Books

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

Articles

[abc2003] Gall Anonim. 'An article', Whatever. 2003.

Links to bibliography entries:

Please read [taoup].

For a guide on DcoBook, see: [walsh-muellner]

This idea was first introduced in [abc2003]

List continuations

Append block elements to a list with the + character.

Code:

1. Step one: rename original file
+
[literal]
--
$ mv myfile.txt myfile_BAK.txt
--
+
2. Step two: create new file
+
[literal]
--
$ touch myfile.txt
--
+
3. Step three: done!

Result:

Step one: rename original file
```
$ mv myfile.txt myfile_BAK.txt
```
Step two: create new file
```
$ touch myfile.txt
```
Step three: done!

Footnotes

Code:

A footnote footnote:[An example footnote.].

A second footnote with a reference ID footnoteref:[note2,Second footnote.].

Finally a reference to the second footnote footnoteref:[note2].

Result:

TODO: this is deprecated

A footnote footnote:[An example footnote.].

A second footnote with a reference ID footnoteref:[note2,Second footnote.].

Finally a reference to the second footnote footnoteref:[note2].

Callouts

$ mv myfile.txt myfile_BAK.txt (1)
$ touch myfile.txt (2)

Rename original file
Create new file

Macros

Links

External links

Code:

https://www.example.com[Example domain]

mailto:me@example.com[Mail me!]

Result:

Example domain

Mail me!

Links to local documents

Code:

A text file can be found link:hello.txt[here]

Result:

TODO: add file hello.txt

A text file can be found link:hello.txt[here]

Links inside document

Code:

[[THEFISH]] The fish is here: +<><+

The fish can be found xref:THEFISH[here]

Result:

The fish is here: <><

The fish can be found here

Inline documents

Images

Code:

image:pripyat.jpg[alt="Soviet-era mural inside post office. Pripyat, Ukraine.",title="Pripyat post office mural"]

image:pripyat.jpg[alt="Soviet-era mural inside post office. Pripyat, Ukraine.",title="Pripyat post office mural. Click for full size.",height=256,link="pripyat.jpg"]

Result:

TODO: add image file

image:pripyat.jpg[alt="Soviet-era mural inside post office. Pripyat, Ukraine.",title="Pripyat post office mural"]

image:pripyat.jpg[alt="Soviet-era mural inside post office. Pripyat, Ukraine.",title="Pripyat post office mural. Click for full size.",height=256,link="pripyat.jpg"]

Asciidoc files

Code:

[listing]
--
include::hello.txt[]
--

Result:

TODO: add file hello.txt

[listing]
--
include::hello.txt[]
--

Comments

Code:

This line gets shown.
// This one doesn't.
This one gets shown too.

Result:

This line gets shown. This one gets shown too.

Conditionals

Code:

+doctitle+:
"{doctitle}"

+foo_attrib+:
"{foo_attrib}"

+OK+ is shown only if +doctitle+ is defined:
ifdef::doctitle[]
+OK+
endif::doctitle[]

+OK+ is shown only if +foo_attrib+ is NOT defined:
ifndef::foo_attrib[]
+OK+
endif::foo_attrib[]

ifdef::doctitle[This line is shown only if +doctitle+ is defined.]

+OK+ is shown only if +doctitle+ OR +foo_attrib+ are defined:
ifdef::doctitle,foo_attrib[]
+OK+
endif::doctitle,foo_attrib[]

+OK+ is shown only if +doctitle+ AND +foo_attrib+ are defined:
ifdef::doctitle+foo_attrib[]
+OK+
endif::doctitle+foo_attrib[]

Result:

doctitle: "AsciiDoc markup testbed"

foo_attrib: "{foo_attrib}"

OK is shown only if doctitle is defined: OK

OK is shown only if foo_attrib is NOT defined: OK

This line is shown only if doctitle is defined.

OK is shown only if doctitle OR foo_attrib are defined: OK

OK is shown only if doctitle AND foo_attrib are defined:

Command macros

Shell commands

sys

Displays stdout output of shell command.

Code:

[listing]
--
\sys::[seq 0 2 10]
--

Result:

sys::[seq 0 2 10]

sys2

Displays stdout & stderr output of shell command.

Code:

[listing]
--
\sys::[(echo "sys, stdout" ; echo "sys, stderr" >&2)]
\sys2::[(echo "sys2, stdout" ; echo "sys2, stderr" >&2)]
--

Result:

sys::[(echo "sys, stdout" ; echo "sys, stderr" >&2)]
sys2::[(echo "sys2, stdout" ; echo "sys2, stderr" >&2)]

eval

Displays the string value of a Python expression

Code:

\eval::["Pyhon interpreter: +" + sys.version + "+"]

Result:

eval::["Pyhon interpreter: " + sys.version + ""]

Tables

Code:

[cols="3,^2,^2,10",options="header"]
|=========================================================
|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 |23:03 | 152 |
Back-to-back with previous interval.

|24-Aug-08 |40:00 | 145 |
Moderately hard interspersed with 3x 3min intervals (2min
hard + 1min really hard taking the HR up to 160).

|=========================================================

Result:

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	23:03	152	Back-to-back with previous interval.
24-Aug-08	40:00	145	Moderately hard interspersed with 3x 3min intervals (2min hard + 1min really hard taking the HR up to 160).

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

23:03

152

Back-to-back with previous interval.

24-Aug-08

40:00

145

Moderately hard interspersed with 3x 3min intervals (2min hard + 1min really hard taking the HR up to 160).

Syntax highlighting

Code:

[source,bash]
--
echo "Hello!"
pwd
--

Result:

echo "Hello!"
pwd

Code:

[source,python]
--
import sys

print("Python interpreter" + sys.version)
--

Result:

import sys

print("Python interpreter" + sys.version)

Math

AsciiMathML

The attribute asciimath needs to be defined.

Code:

asciimath:[x/x={(1,if x!=0),(text{undefined},if x=0):}]

Result:

\$x/x={(1,if x!=0),(text{undefined},if x=0):}\$

LatexMathML

Either define asciimath or latexmath.

The glyphs are too small when latexmath is defined.

Code:

latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$]

Result:

$\sum_{n=1}^\infty \frac{1}{2^n}$