Paragraphs

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.
Newlines within a paragraph are not displayed.

Rubies are red, +
Topazes are blue.

[%hardbreaks]
Ruby is red.
Java is black.

A normal paragraph.

 A paragraph offset by at least one space becomes a literal paragraph.
 All lines in a literal paragraph must be adjacent.

 A literal paragraph is displayed as preformatted text.
 The text is shown in a fixed-width font.
 Spaces and newlines,
 like the ones in this sentence,
 are preserved.

Another normal paragraph.

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

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

Formatted Text

*bold phrase* & **char**acter**s**

_italic phrase_ & __char__acter__s__

*_bold italic phrase_* & **__char__**acter**__s__**

`monospace phrase` & ``char``acter``s``

`*monospace bold phrase*` & ``**char**``acter``**s**``

`_monospace italic phrase_` & ``__char__``acter``__s__``

`*_monospace bold italic phrase_*` &
``**__char__**``acter``**__s__**``

Werewolves are allergic to #cassia cinnamon#.

Did the werewolves read the [.small]#small print#?

Where did all the [.underline]#cores# run off to?

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

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

^super^script phrase

~sub~script phrase

"`double curved quotes`"

'`single curved quotes`'

Olaf's desk was a mess.

All of the werewolves`' desks were a mess.

Olaf had been with the company since the `'60s.

Document Header

= My Document's Title

My document provides...

= My Document's Title
Doc Writer <doc.writer@asciidoctor.org>

My document provides...

= My Document's Title
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2014-01-01

My document provides...

= My Document's Title
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2018-04-11
:toc:
:imagesdir: assets/images
:homepage: https://asciidoctor.org

My document provides...

Section Titles (Headings)

= 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

= Document Title (Level 0)

== Section Level 1

=== Section Level 2

==== Section Level 3

===== Section Level 4

====== Section Level 5

= Section Level 0

[#primitives-nulls]
== Primitive types and null values

Include Files

= Reference Documentation
Lead Developer

This is documentation for project X.

include::basics.adoc[]

include::installation.adoc[]

include::example.adoc[]

include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[]

Lists

* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson

- Edgar Allen Poe
- Sheri S. Tepper
- Bill Bryson

* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1

. Step 1
. Step 2
. Step 3

. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3

. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1

* [*] checked
* [x] also checked
* [ ] not checked
*     normal list item

first term:: definition of first term
second term:: definition of second term

first term::
definition of first term
second term::
definition of second term

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

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

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2

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

 $ gem install asciidoctor

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

|AsciiDoc
|Python

|Asciidoctor
|Ruby
|===

Links

https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]

https://github.com/asciidoctor[Asciidoctor @ *GitHub*]

link:++https://example.org/?q=[a b]++[URL with special characters]

link:https://example.org/?q=%5Ba%20b%5D[URL with special characters]

link:\\server\share\whitepaper.pdf[Whitepaper]

link:index.html[Docs]

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/#fedora

http://discuss.asciidoctor.org[Discuss Asciidoctor, role="external", window="_blank"]

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

https://example.org["Google, Yahoo, Bing^", role="teal"]

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

See <<paragraphs>> to learn how to write paragraphs.

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

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

image::sunset.jpg[]

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

image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]

Figure 1: A mountain sunset

Click image:play.png[Play, title="Play"] to get the party started.

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

image:sunset.jpg[Sunset,150,150,role="right"] What a beautiful sunset!

= Document Title
:data-uri:

Source Code

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

Output literal monospace text such as `+{backtick}+` by
enclosing the text in pluses, then again in backticks.

 Indent the line one space to insert a code snippet

Indent the line one space to insert a code snippet

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

.Gemfile.lock
----
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (1.5.6.1)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 1.5.6.1)
----

.app.rb
[source,ruby]
----
require 'sinatra'

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

require 'sinatra'

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

[source,ruby]
----
require 'sinatra' // <1>

get '/hi' do // <2>
  "Hello World!" // <3>
end
----
<1> Library import
<2> URL mapping
<3> HTTP response body

require 'sinatra' (1)

get '/hi' do (2)
  "Hello World!" (3)
end

----
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)

[source,xml]
----
<section>
  <title>Section Title</title> <!--1-->
</section>
----
<1> The section title is required.

<section>
  <title>Section Title</title> (1)
</section>

[source,ruby]
----
include::app.rb[]
----

:sourcedir: src/main/java

[source,java]
----
include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
----

[source,ruby,indent=0]
----
include::lib/document.rb[lines=5..10]
----

[source,xml]
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

This is normal content.

<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

:source-highlighter: pygments

More Delimited Blocks

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

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

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

.A list
- one
- two
- three

Another paragraph.
====

[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 http://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

[, James Baldwin]
""
Not everything that is faced can be changed.
But nothing can be changed until it is faced.
""

++++
<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>
++++

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

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

puts "I'm a source block!"

:version: 1.5.6.1

[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>1.5.6.1</version>
</dependency>

Block Id, Role and Options

[[goals]]
[role="incremental"]
* Goal 1
* Goal 2

[#goals.incremental]
* Goal 1
* Goal 2

[[free_the_world]][big goal]_free the world_

[#free_the_world.big.goal]_free the world_

[.rolename]`monospace text`

[options="header,footer,autowidth"]
|===
|Cell A |Cell B
|===

[%header%footer%autowidth]
|===
|Cell A |Cell B
|===

Tables

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

[%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
|===

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

[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]!
|===

[%header,format=csv]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===

,===
Artist,Track,Genre

Baauer,Harlem Shake,Hip Hop
,===

|===
include::customers.csv[]
|===

:===
Artist:Track:Genre

Robyn:Indestructable:Dance
:===

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

UI Macros

|===
|Shortcut |Purpose

|kbd:[F11]
|Toggle fullscreen

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

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

|kbd:[\ ]
|Used to escape characters

|kbd:[Ctrl+\]]
|Jump to keyword

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

To save the file, select menu:File[Save].

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

Press the btn:[OK] button when you are finished.

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

Attributes and Substitutions

: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}✔{endsb}]

Check out {url-home}[Asciidoctor]!

{summary}

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

{checkedbox} That's done!

 

​

⁠

'

"

‘

’

“

”

°

+

¦

|

&

<

>

[

]

^

*

~

\

`

::

;;

C++

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

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

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

Escaping Text

\*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.

`A\--Z` connects A to Z in monospace using two dashes.
The dashes are not replaced by an em dash.

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

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

In these cases, the backslash character is automatically removed.

`+Text inside {plus} characters+` is not formatted.
However, special characters like +<+ and +>+ are still escaped.

+++<u>underline me</u>+++ is underlined.

pass:[<u>underline me</u>] is also underlined.

Bibliography

_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,2]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns:
  Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

Markdown Compatibility

# Document Title (Level 0)

## Section Level 1

### Section Level 2

#### Section Level 3

##### Section Level 4

###### Section Level 5

```ruby
require 'sinatra'

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

require 'sinatra'

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

> 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

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

---

- - -

***

* * *