AsciiDoc Syntax Quick Reference

The examples on this page demonstrate the output produced by the built-in HTML converter. An AsciiDoc converter is expected to produce complementary output when generating other output formats, such as PDF, EPUB, and DocBook.

Paragraphs

Example 1. Paragraph
Paragraphs don't require special markup in AsciiDoc.
A paragraph is defined by one or more consecutive lines of text.
Newlines within a paragraph are not displayed.

Leave at least one blank line to begin a new paragraph.
View result of Example 1

Paragraphs don’t require special markup in AsciiDoc. A paragraph is defined by one or more consecutive lines of text. Newlines within a paragraph are not displayed.

Leave at least one blank line to begin a new paragraph.

Example 2. Literal paragraph
A normal paragraph.

 A literal paragraph.
 One or more consecutive lines indented by at least one space.

 The text is shown in a fixed-width (typically monospace) font.
 The lines are preformatted (i.e., as formatted in the source).
 Spaces and newlines,
 like the ones in this sentence,
 are preserved.
View result of Example 2

A normal paragraph.

A literal paragraph.
One or more consecutive lines indented by at least one space.
The text is shown in a fixed-width (typically monospace) font.
The lines are preformatted (i.e., as formatted in the source).
Spaces and newlines,
like the ones in this sentence,
are preserved.
Example 3. Hard line breaks
Roses are red, +
violets are blue.

[%hardbreaks]
A ruby is red.
Java is black.
View result of Example 3

Roses are red,
violets are blue.

A ruby is red.
Java is black.

Example 4. Lead paragraph
[.lead]
This text will be styled as a lead paragraph (i.e., larger font).

This paragraph will not be.
View result of Example 4

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

This paragraph will not be.

The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph if no role is specified on that paragraph.

Text formatting

Example 5. Constrained bold, italic, and monospace
It has *strong* significance to me.

I _cannot_ stress this enough.

Type `OK` to accept.

That *_really_* has to go.

Can't pick one? Let's use them `*_all_*`.
View result of Example 5

It has strong significance to me.

I cannot stress this enough.

Type OK to accept.

That really has to go.

Can’t pick one? Let’s use them all.

Example 6. Unconstrained bold, italic, and monospace
**C**reate, **R**ead, **U**pdate, and **D**elete (CRUD)

That's fan__freakin__tastic!

Don't pass generic ``Object``s to methods that accept ``String``s!

It was Beatle**__mania__**!
View result of Example 6

Create, Read, Update, and Delete (CRUD)

That’s fanfreakintastic!

Don’t pass generic Objects to methods that accept Strings!

It was Beatlemania!

Example 7. Highlight, underline, strikethrough, and custom role
Werewolves are allergic to #cinnamon#.

##Mark##up refers to text that contains formatting ##mark##s.

Where did all the [.underline]#cores# go?

We need [.line-through]#ten# twenty VMs.

A [.myrole]#custom role# must be fulfilled by the theme.
View result of Example 7

Werewolves are allergic to cinnamon.

Markup refers to text that contains formatting marks.

Where did all the cores go?

We need ten twenty VMs.

A custom role must be fulfilled by the theme.

Example 8. Superscript and subscript
^super^script phrase

~sub~script phrase
View result of Example 8

superscript phrase

subscript phrase

Example 9. Smart quotes and apostrophes
"`double curved quotes`"

'`single curved quotes`'

Olaf's desk was a mess.

A ``std::vector```'s size is the number of items it contains.

All of the werewolves`' desks were a mess.

Olaf had been with the company since the `'00s.
View result of Example 9

“double curved quotes”

‘single curved quotes’

Olaf’s desk was a mess.

A std::vector’s size is the number of items it contains.

All of the werewolves’ desks were a mess.

Olaf had been with the company since the ’00s.

Example 10. Autolinks, URL macro, and mailto macro
https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]

devel@discuss.example.org

mailto:devel@discuss.example.org[Discuss]

mailto:join@discuss.example.org[Subscribe,Subscribe me,I want to join!]
View result of Example 10
Example 11. URL macros with attributes
https://discuss.asciidoctor.org[Discuss Asciidoctor,role=external,window=_blank]

https://discuss.asciidoctor.org[Discuss Asciidoctor^]
View result of Example 11
The link: macro prefix is not required when the target starts with a URL scheme like https:. The URL scheme acts as an implicit macro prefix.
If the linked text contains a comma and the text is followed by one or more named attributes, you must enclose the text in double quotes. Otherwise, the text will be cut off at the comma (and the remaining text will get pulled into the attribute parsing).
Example 12. URLs with spaces and special characters
link:++https://example.org/?q=[a b]++[URL with special characters]

https://example.org/?q=%5Ba%20b%5D[URL with special characters]
Example 13. Link to relative file
link:index.html[Docs]
Example 14. Link using a Windows UNC path
link:\\server\share\whitepaper.pdf[Whitepaper]
Example 15. Inline anchors
[[bookmark-a]]Inline anchors make arbitrary content referenceable.

[#bookmark-b]#Inline anchors can be applied to a phrase like this one.#

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

[[bookmark-d,last paragraph]]The xreflabel attribute will be used as link text in the cross-reference link.
Example 16. Cross references
See <<paragraphs>> to learn how to write paragraphs.

Learn how to organize the document into <<section-titles,sections>>.
View result of Example 16

See Paragraphs to learn how to write paragraphs.

Learn how to organize the document into sections.

Example 17. Inter-document cross references
Refer to xref:document-b.adoc#section-b[Section B of Document B] for more information.

If you never return from xref:document-b.adoc[Document B], we'll send help.

Document header

The document header is optional. The header may not contain blank lines and must be separated from the content by at least one blank line.

Example 18. Title
= Document Title

This document provides...
Example 19. Title and author line
= Document Title
Author Name <author@email.org>; Author Name <author@email.org>

This document provides...
Example 20. Title, author line, and revision line
= Document Title
Author Name <author@email.org>
v2.0, 2019-03-22

This document provides...
You cannot have a revision line without an author line.
Example 21. Document header with attribute entries
= Document Title
Author Name <author@email.org>
v2.0, 2019-03-22
:toc:
:homepage: https://example.org

This document provides...

Section titles

When the document type is article (the default), the document can only have one level-0 section title (=), which is the document title (i.e., doctitle).

Example 22. Article section levels
= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title

== Another Level 1 Section Title
View result of Example 22

Document Title (Level 0)

Level 1 Section Title

Level 2 Section Title

Level 3 Section Title

Level 4 Section Title
Level 5 Section Title

Another Level 1 Section Title

The book document type can have additional level-0 section titles, which are interpreted as parts. The presence of at least one part implicitly makes the document a multi-part book.

Example 23. Book section levels
= Document Title (Level 0)

== Level 1 Section Title

= Level 0 Section Title (Part)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title

= Another Level 0 Section Title (Part)
Example 24. Discrete heading (not a section)
[discrete]
=== I'm an independent heading!

Automatic TOC

Example 25. Activate Table of Contents for a document
= Document Title
Doc Writer <doc.writer@email.org>
:toc:

The Table of Content’s title, displayed section depth, and position can be customized.

Include files

Example 26. Include document parts
= Reference Documentation
Lead Developer

This is documentation for project X.

include::basics.adoc[]

include::installation.adoc[]

include::example.adoc[]
Example 27. Include content by tagged regions or lines
include::filename.txt[tag=definition]

include::filename.txt[lines=5..10]
Example 28. Include content from a URL
include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[]
Including content from a URL 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 the allow-uri-read attribute to permit Asciidoctor to read content from a URL.

Lists

Example 29. Unordered list
* List item
** Nested list item
*** Nested list item
* List item
 ** Another nested list item
* List item
View result of Example 29
  • List item

    • Nested list item

      • Nested list item

  • List item

    • Another nested list item

  • List item

A blank line is required before and after a list to separated it from other blocks. You can force two adjacent lists apart by adding a blank attribute list (i.e., []) above the second list or by inserting a blank line followed by a line comment after the first list. If you use a line comment, the convention is to use //- to provide a hint to other authors that it’s serving as a list divider.
Example 30. Unordered list max level nesting
* Level 1 list item
** Level 2 list item
*** Level 3 list item
**** Level 4 list item
***** Level 5 list item
* Level 1 list item
View result of Example 30
  • Level 1 list item

    • Level 2 list item

      • Level 3 list item

        • Level 4 list item

          • Level 5 list item

  • Level 1 list item

The unordered list marker can be changed using a list style (e.g., square).

Example 31. Ordered list
. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3
View result of Example 31
  1. Step 1

  2. Step 2

    1. Step 2a

    2. Step 2b

  3. Step 3

Example 32. Ordered list max level nesting
. Level 1 list item
.. Level 2 list item
... Level 3 list item
.... Level 4 list item
..... Level 5 list item
. Level 1 list item
View result of Example 32
  1. Level 1 list item

    1. Level 2 list item

      1. Level 3 list item

        1. Level 4 list item

          1. Level 5 list item

  2. Level 1 list item

Ordered lists support numeration styles such as lowergreek and decimal-leading-zero.

Example 33. Checklist
* [*] checked
* [x] also checked
* [ ] not checked
* normal list item
View result of Example 33
  • checked

  • also checked

  • not checked

  • normal list item

Example 34. Description list
First term:: The description can be placed on the same line
as the term.
Second term::
Description of the second term.
The description can also start on its own line.
View result of Example 34
First term

The description can be placed on the same line as the term.

Second term

Description of the second term. The description can also start on its own line.

Example 35. Question and answer list
[qanda]
What is the answer?::
This is the answer.

Have you seen my duck?:: No.
View result of Example 35
  1. What is the answer?

    This is the answer.

  2. Have you seen my duck?

    No.

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

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace
View result of Example 36
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

Lists can be indented. Leading whitespace is not significant.
Example 37. 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 (`{plus}`) on a line by itself

* A literal paragraph does not require a list continuation.

 $ cd projects/my-book

* AsciiDoc lists may contain any complex content.
+
|===
|Column 1, Header Row |Column 2, Header Row

|Column 1, Row 1
|Column 2, Row 1
|===
View result of Example 37
  • 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.

    $ cd projects/my-book
  • AsciiDoc lists may contain any complex content.

    Column 1, Header Row Column 2, Header Row

    Column 1, Row 1

    Column 2, Row 1

Images

You can use the imagesdir attribute to avoid hard coding the common path to your images in every image macro. The value of this attribute can be an absolute path, relative path, or base URL. If the image target is a relative path, the attribute’s value is prepended (i.e., it’s resolved relative to the value of the imagesdir attribute). If the image target is a URL or absolute path, the attribute’s value is not prepended.

Example 38. Block image macro
image::sunset.jpg[]

image::sunset.jpg[Sunset]

.A mountain sunset
[#img-sunset]
[caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655]
image::sunset.jpg[Sunset,200,100]

image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]
View result of Example 38
sunset
Sunset
Sunset
Figure 1: A mountain sunset
GitHub mascot

Two colons following the image keyword in the macro (i.e., image::) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., image:) indicates an inline image. (All macros follow this pattern). You use an inline image when you need to place the image in a line of text. Otherwise, you should prefer the block form.

Example 39. Inline image macro
Click image:play.png[] to get the party started.

Click image:pause.png[title="Pause"] when you need a break.
View result of Example 39

Click play to get the party started.

Click pause when you need a break.

Example 40. Inline image macro with positioning role
image:sunset.jpg[Sunset,150,150,role=right] What a beautiful sunset!
View result of Example 40

Sunset What a beautiful sunset!

Example 41. Embedded
= Document Title
:data-uri:

When the data-uri attribute is set, all images in the document—​including admonition icons—​are embedded into the document as data URIs. You can also pass it as a command line argument using -a data-uri.

Videos

Example 42. Block video macro
video::video_file.mp4[]

video::video_file.mp4[width=640,start=60,end=140,opts=autoplay]
Example 43. Embedded YouTube video
video::rPQoq7ThGAU[youtube]
Example 44. Embedded Vimeo video
video::67480300[vimeo]

You can control the video settings using additional attributes and options on the macro.

Keyboard, button, and menu macros

You must set the experimental attribute in the document header to enable these macros.
Example 45. Keyboard macro
|===
|Shortcut |Purpose

|kbd:[F11]
|Toggle fullscreen

|kbd:[Ctrl+T]
|Open a new tab
|===
View result of Example 45
Shortcut Purpose

F11

Toggle fullscreen

Ctrl+T

Open a new tab

Example 46. Menu macro
To save the file, select menu:File[Save].

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

To save the file, select File  Save.

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

Example 47. Button macro
Press the btn:[OK] button when you are finished.

Select a file in the file navigator and click btn:[Open].
View result of Example 47

Press the OK button when you are finished.

Select a file in the file navigator and click Open.

Literals and Source Code

Example 48. Inline literal monospace
Output literal monospace text such as `+{backtick}+` or `+http://localhost:8080+` by enclosing the text in a pair of pluses surrounded by a pair backticks.
View result of Example 48

Output literal monospace text such as {backtick} or http://localhost:8080 by enclosing the text in a pair of pluses surrounded by a pair backticks.

Example 49. Literal paragraph
Normal line.

 Indent line by one space to create a literal line.

Normal line.
View result of Example 49

Normal line.

Indent line by one space to create a literal line.

Normal line.

Example 50. Literal block
....
error: 1954 Forbidden search
absolutely fatal: operation lost in the dodecahedron of doom

Would you like to try again? y/n
....
View result of Example 50
error: 1954 Forbidden search
absolutely fatal: operation lost in the dodecahedron of doom

Would you like to try again? y/n
Example 51. Listing block with title
.Gemfile.lock
----
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (2.0.12)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 2.0.12)
----
View result of Example 51
Listing 1. Gemfile.lock
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (2.0.12)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 2.0.12)
Example 52. Source block with title and syntax highlighting
.Some Ruby code
[source,ruby]
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----
View result of Example 52
Listing 1. Some Ruby code
require 'sinatra'

get '/hi' do
  "Hello World!"
end

You must enable source highlighting by setting the source-highlighter attribute in the document header, CLI, or API.

:source-highlighter: rouge

See Syntax Highlighting to learn which values are accepted when using Asciidoctor.

Example 53. Source block with callouts
[source,ruby]
----
require 'sinatra' // <1>

get '/hi' do // <2>
  "Hello World!" // <3>
end
----
<1> Library import
<2> URL mapping
<3> HTTP response body
View result of Example 53
require 'sinatra' (1)

get '/hi' do (2)
  "Hello World!" (3)
end
1 Library import
2 URL mapping
3 HTTP response body
Example 54. Make callouts non-selectable
----
line of code // <1>
line of code # <2>
line of code ;; <3>
line of code <!--4-->
----
<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.
<4> A callout behind a line comment for XML or SGML languages like HTML.
View result of Example 54
line of code (1)
line of code (2)
line of code (3)
line of code (4)
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.
4 A callout behind a line comment for XML or SGML languages like HTML.
Example 55. Source block content included from a file
[source,ruby]
----
include::app.rb[]
----
Example 56. Source block content included from file relative to source directory
:sourcedir: src/main/java

[source,java]
----
include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
----
Example 57. Strip leading indentation from partial file content
[source,ruby]
----
include::lib/app.rb[tag=main,indent=0]
----

The indent attribute is frequently used when including source code by tagged region or lines. It can be specified on the include directive itself or the enclosing literal, listing, or source block.

When indent is 0, the leading block indent is stripped.

When indent is greater than 0, the leading block indent is first stripped, then a block is indented by the number of columns equal to this value.

Example 58. Source paragraph (no blank lines)
[source,xml]
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

This is normal content.
View result of Example 58
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

This is normal content.

Admonitions

Example 59. Admonition paragraph
NOTE: An admonition draws attention to auxiliary information.

Here are the other built-in admonition types:

TIP: Pro tip...

IMPORTANT: Don't forget...

WARNING: Watch out for...

CAUTION: Ensure that...
View result of Example 59
An admonition draws attention to auxiliary information.

Here are the other built-in admonition types:

Pro tip…​
Don’t forget…​
Watch out for…​
Ensure that…​
Example 60. Admonition block
[NOTE]
====
An admonition block may contain complex content.

.A list
- one
- two
- three

Another paragraph.
====
View result of Example 60

An admonition block may contain complex content.

A list
  • one

  • two

  • three

Another paragraph.

More delimited blocks

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 61. Sidebar block
.Optional Title
****
Sidebars are used to visually separate auxiliary bits of content
that supplement the main text.
****
View result of Example 61
Optional Title

Sidebars are used to visually separate auxiliary bits of content that supplement the main text.

Example 62. Example block
====
Here's a sample AsciiDoc document:

----
= Title of Document
Doc Writer
:toc:

This guide provides...
----

The document header is useful, but not required.
====
View result of Example 62

Here’s a sample AsciiDoc document:

= Title of Document
Doc Writer
:toc:

This guide provides...

The document header is useful, but not required.

Example 63. Blockquotes
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
____
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.
____

[quote, Charles Lutwidge Dodgson, 'Mathematician and author, also known as https://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]']
____
If you don't know where you are going, any road will get you there.
____

"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
View result of Example 63

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

— Abraham Lincoln
Address delivered at the dedication of the Cemetery at Gettysburg
A person who never made a mistake never tried anything new.
— Albert Einstein

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

If you don’t know where you are going, any road will get you there.

— Charles Lutwidge Dodgson
Mathematician and author, also known as Lewis Carroll
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
Example 64. Open blocks
--
An open block can be an anonymous container,
or it can masquerade as any other block.
--

[source]
--
puts "I'm a source block!"
--
View result of Example 64

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

puts "I'm a source block!"
Example 65. Passthrough block
++++
<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="https://gist.github.com/mojavelinux/5333524.js">
</script>
++++
View result of Example 65

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

Example 66. Customize block substitutions
:release-version: 2.0.12

[source,xml,subs=attributes+]
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>{release-version}</version>
</dependency>
----
View result of Example 66
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>2.0.12</version>
</dependency>

Tables

Example 67. Table with a title, two columns, a header row, and two rows of content
.Table Title
|===
|Column 1, Header Row |Column 2, Header Row (1)
(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 Unless the cols attribute is specified, the number of columns is equal to the number of cell separators on the first (non-blank) line.
2 When a blank line follows the first non-blank line, the cells in the first line get promoted to the table header.
View result of Example 67
Table 1. Table Title
Column 1, Header Row Column 2, Header Row

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Example 68. Table with two columns, a header row, and two rows of content
[%header,cols=2*] (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 the cols attribute is the repeat operator. It means repeat the column specification across the remaining columns. In this case, we are repeating the default formatting across 2 columns. When the cells in the header are not defined on a single line, you must use the cols attribute to set the number of columns in the table and the %header option (or options=header attribute) to promote the first row to the table header.
View result of Example 68
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

Example 69. Table with three columns, a header row, and two rows of content
.Applications
[cols="1,1,2"] (1)
|===
|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, the cols attribute has two functions. It specifies that this table has three columns, and it sets their relative widths.
View result of Example 69
Table 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.

Example 70. 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

https://getfirefox.com[Get Firefox]!
|===
View result of Example 70

Firefox

Browser

Mozilla Firefox is an open source web browser.

It’s designed for:

  • standards compliance

  • performance

  • portability

Example 71. Table from CSV data using shorthand
,===
Artist,Track,Genre

Baauer,Harlem Shake,Hip Hop
,===
View result of Example 71
Artist Track Genre

Baauer

Harlem Shake

Hip Hop

Example 72. Table from CSV data
[%header,format=csv]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===
View result of Example 72
Artist Track Genre

Baauer

Harlem Shake

Hip Hop

The Lumineers

Ho Hey

Folk Rock

Example 73. Table from CSV data in file
|===
include::customers.csv[]
|===
Example 74. Table from DSV data using shorthand
:===
Artist:Track:Genre

Robyn:Indestructable:Dance
:===
View result of Example 74
Artist Track Genre

Robyn

Indestructable

Dance

Example 75. 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
|===
View result of Example 75

1

2

3

4

5

6

7

8

9

10

IDs, roles, and options

Example 76. Shorthand method for assigning block ID (anchor) and role
[#goals.incremental]
* Goal 1
* Goal 2
  • To specify multiple roles using the shorthand syntax, delimit them by dots.

  • The order of id and role values in the shorthand syntax does not matter.

Example 77. Formal method for assigning block ID (anchor) and role
[id="goals",role="incremental"]
* Goal 1
* Goal 2
Example 78. Explicit section ID (anchor)
[#null-values]
== Primitive types and null values
Example 79. Assign ID (anchor) and role to inline formatted text
[#id-name.role-name]`monospace text`

[#free-world.goals]*free the world*
Example 80. Shorthand method for assigning block options
[%header%footer%autowidth]
|===
|Header A |Header B
|Footer A |Footer B
|===
Example 81. Formal method for assigning block options
[options="header,footer,autowidth"]
|===
|Header A |Header B
|Footer A |Footer B
|===

// options can be shorted to opts
[opts="header,footer,autowidth"]
|===
|Header A |Header B
|Footer A |Footer B
|===

Comments

Example 82. Line and block comments
// A single-line comment

////
A multi-line comment.

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

Breaks

Example 83. Thematic break (aka horizontal rule)
before

'''

after
View result of Example 83

before


after

Example 84. Page break
<<<

Attributes and substitutions

Example 85. Attribute declaration and usage
:url-home: https://asciidoctor.org
:link-docs: https://asciidoctor.org/docs[documentation]
:summary: 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[{startsb}&#10004;{endsb}]

Check out {url-home}[Asciidoctor]!

{summary}

Be sure to read the {link-docs} too!

{checkedbox} That's done!
View result of Example 85

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.

Be sure to read the documentation too!

[✔] That’s done!

To learn more about the available attributes and substitution groups see:

Example 86. Counter attributes
.Parts{counter2:index:0}
|===
|Part Id |Description

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

|PX-{counter:index}
|Description of PX-{index}
|===
View result of Example 86
Table 1. Parts
Part Id Description

PX-1

Description of PX-1

PX-2

Description of PX-2

Text replacements

Textual symbol replacements
Name Syntax Unicode Replacement Rendered Notes

Copyright

(C)

&#169;

©

Registered

(R)

&#174;

®

Trademark

(TM)

&#8482;

Em dash

--

&#8212;

 — 

Only replaced if between two word characters, between a word character and a line boundary, or flanked by spaces.

When flanked by space characters (e.g., a -- b), the normal spaces are replaced by thin spaces (&#8201;).

Ellipses

...

&#8230;

…​

Single right arrow

->

&#8594;

Double right arrow

=>

&#8658;

Single left arrow

<-

&#8592;

Double left arrow

<=

&#8656;

Typographic apostrophe

Sam's

Sam&#8217;s

Sam’s

The typewriter apostrophe is replaced with the typographic (aka curly or smart) apostrophe.

Any named, numeric or hexadecimal XML character reference is supported.

Escaping substitutions

Example 87. Backslash
\*Stars* isn't displayed as bold text.
The asterisks around it are preserved.

\&sect; appears as an entity reference.
It's not converted into the section symbol (&sect;).

\=> The backslash prevents the equals sign followed by a greater
than sign from combining to form a double arrow character (=>).

\[[Word]] is not interpreted as an anchor.
The double brackets around it are preserved.

[\[[Word]]] is not interpreted as a bibliography anchor.
The triple brackets around it are preserved.

The URL \https://example.org isn't converted into an active link.
View result of Example 87

*Stars* isn’t displayed as bold text. The asterisks around it are preserved.

&sect; appears as an entity reference. It’s not converted into the section symbol (§).

=> The backslash prevents the equals sign followed by a greater than sign from combining to form a double arrow character (⇒).

[[Word]] is not interpreted as an anchor. The double brackets around it are preserved.

[[[Word]]] is not interpreted as a bibliography anchor. The triple brackets around it are preserved.

The URL https://example.org isn’t converted into an active link.

Example 88. Single and double plus inline macros
Text between + characters, such as +/document/{id}+
is not substituted.
However, special characters like +<+ and +>+
are still escaped.

You can write `C++{plus}{plus}++` as `+{cpp}+`.
If you need to reference another {pp} language,
you can write it as `+SQL{pp}+`.
View result of Example 88

Text between + characters, such as /document/{id} is not substituted. However, special characters like < and > are still escaped.

You can write C{plus}{plus} as {cpp}. If you need to reference another ++ language, you can write it as SQL{pp}.

Example 89. Triple plus inline macro and inline pass macro
+++<u>underline me</u>+++ is underlined.

pass:[<u>underline me</u>] is also underlined.
View result of Example 89

underline me is underlined.

underline me is also underlined.

Bibliography

Example 90. Bibliography with inbound references
_The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.

[bibliography]
== References

* [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer:
From Journeyman to Master. Addison-Wesley. 1999.
* [[[gof,gang]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides.
Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.
View result of Example 90

The Pragmatic Programmer [pp] should be required reading for all developers. To learn all about design patterns, refer to the book by the “Gang of Four” [gang].

References

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

  • [gang] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

Footnotes

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

A bold statement!footnote:disclaimer[Opinions are my own.]

Another bold statement.footnote:disclaimer[]
View result of Example 91

A statement.[1]

A bold statement![2]

Another bold statement.[2]


1. Clarification about this statement.
2. Opinions are my own.

Markdown compatibility

Markdown compatible syntax is only available when using Asciidoctor.

Example 92. Markdown-style headings
# Document Title (Level 0)

## Section Level 1

### Section Level 2

#### Section Level 3

##### Section Level 4

###### Section Level 5
View result of Example 92

Document Title (Level 0)

Section Level 1

Section Level 2

Section Level 3

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

get '/hi' do
  "Hello World!"
end
```
View result of Example 93
require 'sinatra'

get '/hi' do
  "Hello World!"
end
Example 94. 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
View result of Example 94

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
Example 95. 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.
View result of Example 95

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.

Example 96. Markdown-style thematic breaks
---

- - -

***

* * *
View result of Example 96