Note: this reference is adapted from: https://gist.github.com/mojavelinux/8198e5a5ac2570a0cf30, by Dan Allen and Sarah White

AsciiDoc is a mature, lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. This guide is a quick reference for the common formatting markup and document elements in the AsciiDoc syntax.

Note

Several examples focus on the output generated by the HTML backend. AsciiDoc produces complementary output when generating DocBook.

Most features labeled “Asciidoctor only” can be made available to the native AsciiDoc processor by using this AsciiDoc configuration file from the Asciidoctor project.

Paragraphs

Normal
Paragraphs don't require any special markup in AsciiDoc.
A paragraph is just one or more lines of consecutive text.

To begin a new paragraph, separate it by at least one blank line.

Paragraphs don’t require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text.

To begin a new paragraph, separate it by at least one blank line.

Line breaks
To preserve a line break, end the line in a space followed by a plus sign. +
This results in a visible line break (e.g., `<br>`) between the lines.

To preserve a line break, end the line in a space followed by a plus sign.
This results in a visible line break (e.g.,<br>) between the lines.

Literal
A normal paragraph.

 A sequence of lines that begin with at least one space is a literal paragraph.
 Literal paragraphs are treated as preformatted text.
 The text is shown in a fixed-width font
 and endlines are preserved.

Another normal paragraph.

A normal paragraph.

A sequence of lines that begin with at least one space is a literal paragraph.
Literal paragraphs are treated as preformatted text.
The text is shown in a fixed-width font
and endlines are preserved.

Another normal paragraph.

Admonition
NOTE: An admonition paragraph draws the reader's attention to
auxiliary information.
Its purpose is determined by the label
at the beginning of the paragraph.

Here are the other built-in admonition types:

TIP: Pro tip...

IMPORTANT: Don't forget...

WARNING: Watch out for...

CAUTION: Ensure that...
Note
An admonition paragraph draws the reader’s attention to auxiliary information. Its purpose is determined by the label at the beginning of the paragraph.

Here are the other built-in admonition types:

Tip
Pro tip…​
Important
Don’t forget…​
Warning
Watch out for…​
Caution
Ensure that…​
Note
You can also create admonition blocks.
Lead paragraph
[.lead]
This text will be styled as a lead paragraph (i.e., larger font).

This text will be styled as a lead paragraph (i.e., larger font).

Note
The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph.
More Paragraph, Admonition and Literal Block Examples

See these sections in the Asciidoctor User Manual for more information and examples.

Formatted Text

Bold, Italic, and Monospace
_italic phrase_

__i__talic le__tt__ers

*bold phrase*

**b**old le**tt**ers

*_bold italic phrase_*

**__b__**old italic le**__tt__**ers

`monospace phrase` and le``tt``ers

`_monospace italic phrase_` and le``__tt__``ers

`*monospace bold phrase*` and le``**tt**``ers

`*_monospace bold italic phrase_*` and le``**__tt__**``ers

`+inline literal passthrough+` (monospace text without substitutions)

italic phrase

italic letters

bold phrase

bold letters

bold italic phrase

bold italic letters

monospace phraseand letters

monospace italic phraseand letters

monospace bold phraseand letters

monospace bold italic phraseand letters

inline literal passthrough(monospace text without substitutions)

Custom Styling
Do werewolves believe in [small]#small print#?

[big]##O##nce upon an infinite loop.

Do werewolves believe in small print?

Once upon an infinite loop.

Superscript and Subscript
^super^script phrase

~sub~script phrase

superscript phrase

subscript phrase

Curved Quotes
'`single smart quotes`'

"`double smart quotes`"

‘single smart quotes’

“double smart quotes”

More Text Formatting Examples

See these sections in the Asciidoctor User Manual for more information and examples.

Document Header

Important
A header is optional. When you do add a header to your document, the only required element is a title.
Caution
The header may not contain blank lines and must be offset from the content by at least one blank line.
Title only
//toc::[]

= My Document's Title

My document provides...
Title and author line
= My Document's Title
Doc Writer <doc.writer@asciidoctor.org>

My document provides...
Title, author line and revision line
= My Document's Title
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2014-01-01

My document provides...
Important
You cannot have a revision line without an author line.
Document header with attributes
= My Document's Title
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2014-01-01
:toc:
:imagesdir: assets/images
:homepage: http://asciidoctor.org

My document provides...

Section Titles (Headers)

Article doctype
= Document Title (Level 0)

== Level 1 Section

=== Level 2 Section

==== Level 3 Section

===== Level 4 Section

====== Level 5 Section

== Another Level 1 Section

Document Title (Level 0)

Section Level 1

Section Level 2

Section Level 3

Section Level 4
Section Level 5
Warning
When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header.
Note
The number of equal signs matches the heading level in the HTML output. For example, Section Level 1 becomes an<h2>heading.
Book doctype
= Document Title (Level 0)

== Section Level 1

=== Section Level 2

==== Section Level 3

===== Section Level 4

====== Section Level 5

= Section Level 0

Document Title (Level 0)

Section Level 1

Section Level 2

Section Level 3

Section Level 4
Section Level 5

Section Level 0

Explicit id
[[primitives-nulls]]
== Primitive types and null values
Section anchors and links (Asciidoctor only)
sectanchors

When this document attribute is set, a section icon anchor appears in front of the section title.

sectlinks

When this document attribute is set, the section titles become links.

Note
Section title anchors depend on the default Asciidoctor stylesheet to render properly.

Include Files

Document parts
= Reference Documentation
Lead Developer

This is documentation for project X.

include::basics.adoc[]

include::installation.adoc[]

include::example.adoc[]
Caution
Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed.
Include content from a URI
:asciidoctor-source: https://raw.github.com/asciidoctor/asciidoctor/master

include::{asciidoctor-source}/README.adoc[]
Note
Including content from a URI is potentially dangerous, so it’s disabled if the safe mode is SECURE or greater. Assuming the safe mode is less than SECURE, you must also set theallow-uri-readattribute to permit Asciidoctor to read content from a URI.

Horizontal Rules and Page Breaks

Horizontal rule
'''

Page break
<<<

Lists

Unordered, basic
* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson

//^

* Kevin Spacey
* Jeremy Piven
  • Edgar Allen Poe

  • Sheri S. Tepper

  • Bill Bryson

  • Kevin Spacey

  • Jeremy Piven

Note
Blank lines are required before and after a list.
Tip
You can force two lists apart with a line comment, as the previous example demonstrates. The text in the comment, (^), is optional, but serves as a hint to other authors that this line serves as an "end of list" marker.
Unordered, max nesting
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
  • level 1

    • level 2

      • level 3

        • level 4

          • level 5

  • level 1

Tip
The unordered list marker can be changed using block styles.
Checklist
- [*] checked
- [x] also checked
- [ ] not checked
-     normal list item
  • ✓ checked

  • ✓ also checked

  • ❏ not checked

  • normal list item

Ordered, basic
. Step 1
. Step 2
. Step 3
  1. Step 1

  2. Step 2

  3. Step 3

Ordered, nested
. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3
  1. Step 1

  2. Step 2

    1. Step 2a

    2. Step 2b

  3. Step 3

Ordered, max nesting
. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1
  1. level 1

    1. level 2

      1. level 3

        1. level 4

          1. level 5

  2. level 1

Tip
For ordered lists, Asciidoctor supports numeration styles such aslowergreekanddecimal-leading-zero.
Labeled, single-line
first term:: definition of first term
section term:: definition of second term
first term

definition of first term

section term

definition of second term

Labeled, multi-line
first term::
definition of first term
section term::
definition of second term
first term

definition of first term

section term

definition of second term

Q&A
[qanda]
What is Asciidoctor?::
  An implementation of the AsciiDoc processor in Ruby.
What is the answer to the Ultimate Question?:: 42
  1. What is Asciidoctor?

    An implementation of the AsciiDoc processor in Ruby.

  2. What is the answer to the Ultimate Question?

    42

Mixed
Operating Systems::
  Linux:::
    . Fedora
      * Desktop
    . Ubuntu
      * Desktop
      * Server
  BSD:::
    . FreeBSD
    . NetBSD

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace
Operating Systems
Linux
  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD
  1. FreeBSD

  2. NetBSD

Cloud Providers
PaaS
  1. OpenShift

  2. CloudBees

IaaS
  1. Amazon EC2

  2. Rackspace

Tip
Lists can be indented. Leading whitespace is not significant.
Complex content in outline lists
* Every list item has at least one paragraph of content,
  which may be wrapped, even using a hanging indent.
+
Additional paragraphs or blocks are adjoined by putting
a list continuation on a line adjacent to both blocks.
+
list continuation:: a plus sign (+) on a line by itself

* A literal paragraph does not require a list continuation.

 $ gem install asciidoctor

* AsciiDoc lists may contain any complex content.
+
[cols="2", options="header"]
|===
|Application
|Language

|AsciiDoc
|Python

|Asciidoctor
|Ruby
|===
  • Every list item has at least one paragraph of content, which may be wrapped, even using a hanging indent.

    Additional paragraphs or blocks are adjoined by putting a list continuation on a line adjacent to both blocks.

    list continuation

    a plus sign (+) on a line by itself

  • A literal paragraph does not require a list continuation.

    $ gem install asciidoctor
  • AsciiDoc lists may contain any complex content.

    ApplicationLanguage

    AsciiDoc

    Python

    Asciidoctor

    Ruby

External
http://asciidoctor.org - automatic!

http://asciidoctor.org[Asciidoctor]

https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
Relative
link:index.html[Docs]
Email and IRC
devel@discuss.arquillian.org

mailto:devel@discuss.arquillian.org[Discuss Arquillian]

mailto:devel-join@discuss.arquillian.org[Subscribe, Subscribe me, I want to join!]

irc://irc.freenode.org/#asciidoctor
Link with attributes (Asciidoctor only)
http://discuss.asciidoctor.org[Discuss Asciidoctor, role="external", window="_blank"]

http://discuss.asciidoctor.org[Discuss Asciidoctor^]

http://search.example.com["Google, Yahoo, Bing^", role="teal"]
Note
Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. To enable them, you must set thelinkattrsattribute on the document. When they are enabled, you must quote the link text if it contains a comma.
Inline anchors
[[bookmark-a]]Inline anchors make arbitrary content referenceable.

anchor:bookmark-b[]Use a cross reference to link to this location.

Inline anchors make arbitrary content referenceable.

Use a cross reference to link to this location.

Internal cross references
See <<paragraphs>> to learn how to write paragraphs.

Learn how to organize the document into <<section-titles,sections>>.

See Paragraphs to learn how to write paragraphs.

Learn how to organize the document into sections.

Inter-document cross references (Asciidoctor only)
Refer to <<document-b.adoc#section-b,Section B>> for more information.

See you when you get back from <<document-b#section-b,Section B>>!

Images

Block
image::https://live.staticflickr.com/5293/5448336655_36681dd703_n.jpg[]

image::https://live.staticflickr.com/5293/5448336655_36681dd703_n.jpg[Sunset]

[[img-sunset]]
.A mountain sunset
image::sunset.jpg[Sunset, 300, 200, link="http://www.flickr.com/photos/javh/5448336655"]

image::http://asciidoctor.org/images/octocat.jpg[GitHub mascot]
5448336655 36681dd703 n
Sunset
Sunset
A mountain sunset
GitHub mascot
Important
Images are resolved relative to the value of the imagesdirdocument attribute, which defaults to an empty value. Theimagesdirattribute can be an absolute path, relative path or base URL. If the image target is a URL or absolute path, theimagesdirprefix is not added.
Tip
You should use theimagesdirattribute to avoid hard coding the shared path to your images in every image macro.
Image macro using positioning role
image:https://live.staticflickr.com/5293/5448336655_36681dd703_n.jpg[Sunset,150,150,role="right"] What a beautiful sunset!

Sunset What a beautiful sunset!

Tip
There are a variety of attributes available to position and frame images.
Inline
Click image:icons/play.png[Play, title="Play"] to get the party started.

Click image:icons/pause.png[title="Pause"] when you need a break.

Click Play to get the party started.

Click pause when you need a break.

Embedded
= Document Title
:data-uri:
Note
When thedata-uriattribute is set, all images in the document–including admonition icons–are embedded into the document as data URIs.
Tip
Instead of declaring thedata-uriattribute in the document, you can pass it as a command-line argument using-a data-uri.

Videos

Block
video::video_file.mp4[]

video::video_file.mp4[width=640, start=60, options=autoplay]
Embedded Youtube video
video::rPQoq7ThGAU[youtube]
Embedded Vimeo video
video::67480300[vimeo]
Tip
You can control the video settings using additional attributes and options on the macro.

Source Code

Inline
Reference code like `types` or `methods` inline.

Reference code liketypesormethodsinline.

Literal line
 Indent the line one space to insert a code snippet
Indent the line one space to insert a code snippet
Literal block
....
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
....
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
Listing block with title, no syntax highlighting
.Gemfile.lock
----
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (0.1.4)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 0.1.4)
----
Gemfile.lock
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (0.1.4)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 0.1.4)
Code block with title and syntax highlighting
[source,ruby]
.app.rb
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----
app.rb
require 'sinatra'

get '/hi' do
  "Hello World!"
end
Code block with callouts
[source,ruby]
----
require 'sinatra' <1>

get '/hi' do      <2>
  "Hello World!"  <3>
end
----
<1> Library import
<2> URL mapping
<3> Content for response
require 'sinatra' (1)

get '/hi' do      (2)
  "Hello World!"  (3)
end
  1. Library import

  2. URL mapping

  3. Content for response

Code block with non-selectable callouts
----
line of code  // <1>
line of code  # <2>
line of code  ;; <3>
----
<1> A callout behind a line comment for C-style languages.
<2> A callout behind a line comment for Ruby, Python, Perl, etc.
<3> A callout behind a line comment for Clojure.
line of code  // (1)
line of code  # (2)
line of code  ;; (3)
  1. A callout behind a line comment for C-style languages.

  2. A callout behind a line comment for Ruby, Python, Perl, etc.

  3. A callout behind a line comment for Clojure.

XML code block with a non-selectable callout
[source,xml]
----
<section>
  <title>Section Title</title> <!--1-->
</section>
----
<1> The section title is required.
<section>
  <title>Section Title</title> <!--(1)-->
</section>
  1. The section title is required.

Code block sourced from file
[source,ruby]
----
include::app.rb[]
----
Code block sourced from file relative to source directory
:sourcedir: src/main/java

[source,java]
----
include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
----
Strip leading indentation from source
[source,ruby,indent=0]
----
include::lib/document.rb[lines=5..10]
----
Note
  • Whenindentis 0, the leading block indent is stripped (tabs are replaced with 4 spaces).

  • Whenindentis > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value.

Code block without delimiters (no blank lines)
[source,xml]
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">
Important

Syntax highlighting is enabled by setting thesource-highlighterattribute in the document header or passed as an argument.

:source-highlighter: pygments

The valid options for arecoderay,highlight.js,prettify, andpygments.

More Delimited Blocks

Sidebar
.AsciiDoc history
****
AsciiDoc was first released in Nov 2002 by Stuart Rackham.
It was designed from the start to be a shorthand syntax
for producing professional documents like DocBook and LaTeX.
****
AsciiDoc history

AsciiDoc was first released in Nov 2002 by Stuart Rackham. It was designed from the start to be a shorthand syntax for producing professional documents like DocBook and LaTeX.

Note
Any block can have a title, positioned above the block. A block title is a line of text that starts with a dot. The dot cannot be followed by a space.
Example
.Sample document
====
Here's a sample AsciiDoc document:

[listing]
....
= Title of Document
Doc Writer
:toc:

This guide provides...
....

The document header is useful, but not required.
====
Sample document

Here’s a sample AsciiDoc document:

= Title of Document
Doc Writer
:toc:

This guide provides...

The document header is useful, but not required.

Admonition
[NOTE]
====
An admonition block may contain complex content.

.A list
- one
- two
- three

Another paragraph.
====
Note

An admonition block may contain complex content.

A list:

  • one

  • two

  • three

Another paragraph.

Tip

Asciidoctor can "draw" icons using Font Awesome and CSS.

To use this feature, set the value of theiconsdocument attribute tofont. Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block.

Icons can also be used inline and styled.

Blockquote
[quote, Abraham Lincoln, Soldiers' National Cemetery Dedication]
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...
____

[quote, Albert Einstein]
A person who never made a mistake never tried anything new.

____
A person who never made a mistake never tried anything new.
____

Four score and seven years ago our fathers brought forth on this continent a new nation…​

— Abraham Lincoln
Soldiers' National Cemetery Dedication
A person who never made a mistake never tried anything new.
— Albert Einstein

A person who never made a mistake never tried anything new.

Abbreviated blockquote (Asciidoctor only)
"I hold it that a little rebellion now and then is a good thing,
and as necessary in the political world as storms in the physical."
-- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.
— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11
Air quotes (Asciidoctor only)

As a tip of the hat to Dick, Asciidoctor recognizes text between "air quotes" as a quote block. Air quotes are the best thing since fenced code blocks.

[, Richard M. Nixon]
""
When the President does it, that means that it's not illegal.
""

"" When the President does it, that means that it’s not illegal. ""

Passthrough
++++
<p>
Content in a passthrough block is passed to the output unprocessed.
That means you can include raw HTML, like this embedded Gist:
</p>

<script src="http://gist.github.com/mojavelinux/5333524.js">
</script>
++++

Content in a passthrough block is passed to the output unprocessed. That means you can include raw HTML, like this embedded Gist:

Open
--
An open block can be an anonymous container,
or it can masquerade as any other block.
--

[source]
--
puts "I'm a source block!"
--

An open block can be an anonymous container, or it can masquerade as any other block.

puts "I'm a source block!"
Custom substitutions
:version: 0.1.4

[source,xml]
[subs="verbatim,attributes"]
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>{version}</version>
</dependency>
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>0.1.4</version>
</dependency>

Block Id, Role and Options

Traditional markup method for assigning blockidandrole
[[goals]]
[role="incremental"]
* Goal 1
* Goal 2
Shorthand markup method for assigning blockidandrole(Asciidoctor only)
[#goals.incremental]
* Goal 1
* Goal 2
Tip
  • To specify multiple roles using the shorthand syntax, separate them by dots.

  • The order ofidandrolevalues in the shorthand syntax does not matter.

Traditional markup method for assigning quoted text anchor (id) androle
[[free_the_world]][big goal]_free the world_
Shorthand markup method for assigning quoted text anchor (id) androle(Asciidoctor only)
[#free_the_world.big.goal]_free the world_
Role assigned to text enclosed in backticks
[rolename]`escaped monospace text`
Traditional markup method for assigning blockoptions
[options="header,footer,autowidth"]
|===
|Cell A |Cell B
|===
Shorthand markup method for assigning blockoptions(Asciidoctor only)
[%header%footer%autowidth]
|===
|Cell A |Cell B
|===

Comments

Line
// A single-line comment.
Tip
Single-line comments can be used to divide elements, such as two adjacent lists.
Block
////
A multi-line comment.

Notice it's a delimited block.
////

Tables

Table with a title, three columns, a header, and two rows of content
.Table Title
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3 (1)
(2)
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
  1. Unless thecolsattribute is specified, the number of columns is equal to the number of vertical bars on the first non-blank line inside the block delimiters.

  2. When a blank line follows a single line of column titles, the column titles row will be styled as a header row by default.

Table Title
Name of Column 1Name of Column 2Name of Column 3

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 3, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 3, row 2

Table with two columns, a header, and two rows of content
[cols="2*", options="header"] (1)
|===
|Name of Column 1
|Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===
  1. The*in thecolsattribute is the repeat operator. It means repeat the column specification for the remainder of columns. In this case, it means to repeat the default formatting across 4 columns. When the header row is not defined on a single line, you must use thecolsattribute to set the number of columns andoptionsattributes to make the first row a header.

Name of Column 1Name of Column 2

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Table with three columns, a header, and two rows of content
[cols="1,1,2", options="header"] (1)
.Applications
|===
|Name
|Category
|Description

|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.
It's designed for standards compliance,
performance, portability.

|Arquillian
|Testing
|An innovative and highly extensible testing platform.
Empowers developers to easily create real, automated tests.
|===
  1. In this example, thecolsattribute has two functions. It specifies that this table has three columns, and it sets their relative widths.

Applications
NameCategoryDescription

Firefox

Browser

Mozilla Firefox is an open-source web browser. It’s designed for standards compliance, performance, portability.

Arquillian

Testing

An innovative and highly extensible testing platform. Empowers developers to easily create real, automated tests.

Table with column containing AsciiDoc content
[cols="2,2,5a"]
|===
|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.

It's designed for:

* standards compliance
* performance
* portability

http://getfirefox.com[Get Firefox]!
|===

Firefox

Browser

Mozilla Firefox is an open-source web browser.

It’s designed for:

  • standards compliance

  • performance

  • portability

Table from CSV data
[format="csv", options="header"]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===
ArtistTrackGenre

Baauer

Harlem Shake

Hip Hop

The Lumineers

Ho Hey

Folk Rock

Table from CSV data using shorthand (Asciidoctor only)
,===
Artist,Track,Genre

Baauer,Harlem Shake,Hip Hop
,===
ArtistTrackGenre

Baauer

Harlem Shake

Hip Hop

Table from DSV data using shorthand (Asciidoctor only)
:===
Artist:Track:Genre

Robyn:Indestructable:Dance
:===
ArtistTrackGenre

Robyn

Indestructable

Dance

Table with formatted, aligned and merged cells
[cols="e,m,^,>s", width="25%"]
|===
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|===

1

2

3

4

5

6

7

8

9

10

UI Macros

Important
You must set theexperimentalattribute in the document header to enable these macros.
Keyboard shortcuts (inlinekbdmacro)
|===
|Shortcut |Purpose

|kbd:[F11]
|Toggle fullscreen

|kbd:[Ctrl+T]
|Open a new tab

|kbd:[Ctrl+Shift+N]
|New incognito window

|kbd:[Ctrl + +]
|Increase zoom
|===
ShortcutPurpose

F11

Toggle fullscreen

Ctrl+T

Open a new tab

Ctrl+Shift+N

New incognito window

Ctrl++

Increase zoom

Menu selections (inlinemenumacro)
To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

To save the file, select File Save.

Select View Zoom Reset to reset the zoom level to the default setting.

Buttons (inlinebtnmacro)
Press the btn:[OK] button when you are finished.

Select a file in the file navigator and click btn:[Open].

Press the OK button when you are finished.

Select a file in the file navigator and click Open.

Attributes and Substitutions

Attribute declaration and usage
:homepage: http://asciidoctor.org
:docslink: http://asciidoctor.org/docs[Asciidoctor's Docs]
:desc: Asciidoctor is a mature, plain-text document format for +
       writing notes, articles, documentation, books, and more. +
       It's also a text processor & toolchain for translating +
       documents into various output formats (i.e., backends), +
       including HTML, DocBook, PDF and ePub.
:checkedbox: pass:normal[`[&#10004;]`]

Check out {homepage}[Asciidoctor]!

{desc}

Check out {docslink} too!

{checkedbox} That's done!

Check out Asciidoctor!

Asciidoctor is a mature, plain-text document format for writing notes, articles, documentation, books, and more. It’s also a text processor & toolchain for translating documents into various output formats (i.e., backends), including HTML, DocBook, PDF and ePub.

Check out Asciidoctor’s Docs too!

[✔]That’s done!

Attribute assignment precedence (highest to lowest)
  • Attribute passed to the API or CLI that does not end in@

  • Attribute defined in the document

  • Attribute passed to the API or CLI that ends in@

  • Intrinsic attribute value (default values)

Tip
To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an@symbol to the end of the attribute value.
Built-in literal attributes
Attribute referenceReplacementRendered
\{lt}
<

<

\{gt}
>

>

\{amp}
&

&

\{startsb}
[

[

\{endsb}
]

]

\{vbar}
|

|

\{caret}
^

^

\{asterisk}
*

*

\{tilde}
~

~

\{apostrophe}
'

'

\{backslash}
\

\

\{backtick}
`

`

\{two-colons}
::

::

\{two-semicolons}
;;

;;

Built-in entity attributes
Attribute referenceReplacementRendered
\{empty}
_nothing_
\{sp}, \{space}
_single space_

\{nbsp}
\&#160;

\{zwsp}
\&#8203;

\{wj}
\&#8288;

\{apos}
\&#39;

'

\{quot}
\&#34;

"

\{lsquo}
\&#8216;

\{rsquo}
\&#8217;

\{ldquo}
\&#8220;

\{rdquo}
\&#8221;

\{deg}
\&#176;

°

\{plus}
\&#43;

+

\{brvbar}
\&#166;

¦

Built-in data attributes
AttributeDescription

asciidoctor

Calls the processor

asciidoctor-version

Version of the processor

backend

Backend used to render document

docdate

Last modified date

docdatetime

Last modified date and time

docdir

Name of document directory

docfile

Name of document file

doctime

Last modified time

doctitle

The title of the document

doctype

Document’s doctype (e.g., article)

localdate

Local date when rendered

localdatetime

Local date and time when rendered

localtime

Local time when rendered

Named substitutions
none

Disables substitutions

normal

Performs all substitutions except for callouts

verbatim

Replaces special characters and processes callouts

specialcharacters

Replaces<,>, and&with their corresponding entities

quotes

Applies text formatting

attributes

Replaces attribute references

replacements

Substitutes textual and character reference replacements

macros

Processes macros

post_replacements

Replaces the line break character (+)

Counter attributes
[caption=""]
.Parts{counter2:index:0}
|===
|Part Id |Description

|PX-{counter:index}
|Description of PX-{index}

|PX-{counter:index}
|Description of PX-{index}
|===
Parts
Part IdDescription

PX-1

Description of PX-1

PX-2

Description of PX-2

Text Replacement

Textual symbol replacements
NameSyntaxUnicode ReplacementRenderedNotes

Copyright

\(C)
\&#169;

©

Registered

\(R)
\&#174;

®

Trademark

\(TM)
\&#8482;

Em dash

\--
\&#8212;

When space is detected on either side of the em dash, the thin space numeric character entity (&#8201;) is also substituted into the document.

ellipses

\...
\&#8230;

…​

right single arrow

\->
\&#8594;

right double arrow

\=>
\&#8658;

left single arrow

\<-
\&#8592;

left double arrow

\<=
\&#8656;

apostrophe

Sam\'s
Sam\&#8217;s

Sam’s

The vertical form apostrophe is replaced with the curved form apostrophe.

Tip
Any named, numeric or hex XML entity reference is supported.

Escaping Text

Backslash
\*Stars* is not rendered as bold text.
The asterisks around the word are preserved.

\{author} is not resolved to the author name.
The curly brackets around the word are preserved.

The backslash character is automatically removed.

*Stars* is not rendered as bold text. The asterisks around the word are preserved.

{author} is not resolved to the author name. The curly brackets around the word are preserved.

The backslash character is automatically removed.

Double dollar
$$*Stars*$$ is not rendered as bold text.
The asterisks around the word are preserved.

$$&amp;$$ renders as an XML entity instead of &.

*Stars* is not rendered as bold text. The asterisks around the word are preserved.

&amp; renders as an XML entity instead of &.

Triple plus and inline passthrough macro
+++<u>underline me</u>+++ renders as underlined text.

pass:[<u>underline me</u>] also renders as underlined text.

underline me renders as underlined text.

underline me also renders as underlined text.

Backticks
`Text in {backticks}` renders exactly as entered, in `monospace`.
The attribute reference is not resolved.

Text in {backticks}renders exactly as entered, inmonospace. The attribute reference is not resolved.

Table of Contents (ToC)

Document with ToC
= AsciiDoc Writer's Guide
Doc Writer <doc.writer@asciidoc.org>
v1.0, 2013-01-01
:toc:
Document with ToC positioned on the right
= AsciiDoc Writer's Guide
Doc Writer <doc.writer@asciidoc.org>
v1.0, 2013-01-01
:toc: right
Tip
The ToC "title, levels, and positioning" can be customized.

Bibliography

References
'The Pragmatic Programmer' <<prag>> should be required reading for
all developers.

[bibliography]
- [[[prag]]] Andy Hunt & Dave Thomas. 'The Pragmatic Programmer:
  From Journeyman to Master'. Addison-Wesley. 1999.
- [[[seam]]] Dan Allen. 'Seam in Action'. Manning Publications.
  2008.

'The Pragmatic Programmer' [prag] should be required reading for all developers.

  • [prag] Andy Hunt & Dave Thomas. 'The Pragmatic Programmer: From Journeyman to Master'. Addison-Wesley. 1999.

  • [seam] Dan Allen. 'Seam in Action'. Manning Publications. 2008.

Footnotes

Normal and reusable footnotes
A statement.footnote:[Clarification about this statement.]

A bold statement.footnoteref:[disclaimer,These opinions are my own.]

Another bold statement.footenoteref:[disclaimer]

A statement.[1]

A bold statement.[2]

Another bold statement.footenote:[disclaimer]


1. Clarification about this statement.
2. disclaimer,These opinions are my own.

Markdown Compatibility

Important
Markdown compatibility is only available by default in Asciidoctor. You can configure AsciiDoc (Python) to recognize this syntax by putting the AsciiDoc compatibility file from Asciidoctor in the same directory as the document being processed.
Markdown-style headings
# Document Title (Level 0)

## Section Level 1

### Section Level 2

#### Section Level 3

##### Section Level 4

###### Section Level 5

Document Title (Level 0)

Section Level 1

Section Level 2

Section Level 3

Section Level 4
Section Level 5
Fenced code block with syntax highlighting
```ruby
require 'sinatra'

get '/hi' do
  "Hello World!"
end
```
require 'sinatra'

get '/hi' do
  "Hello World!"
end
Markdown-style blockquote
> I hold it that a little rebellion now and then is a good thing,
> and as necessary in the political world as storms in the physical.
> -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11

I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.

— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11
Markdown-style blockquote with block content
> > What's new?
>
> I've got Markdown in my AsciiDoc!
>
> > Like what?
>
> * Blockquotes
> * Headings
> * Fenced code blocks
>
> > Is there more?
>
> Yep. AsciiDoc and Markdown share a lot of common syntax already.

What’s new?

I’ve got Markdown in my AsciiDoc!

Like what?

  • Blockquotes

  • Headings

  • Fenced code blocks

Is there more?

Yep. AsciiDoc and Markdown share a lot of common syntax already.

Markdown-style horizontal rules
---

- - -

***

* * *




User Manual and Help

To learn more about Asciidoctor and its capabilities, check out the other Asciidoctor guides and its User Manual. Also, don’t forget to join the Asciidoctor mailing list, where you can ask questions and leave comments.