Basic Inline Text Formatting

Bold & Italic

You can bold and italic entire phrases, a word, and characters in a word.

Bold and italic inline formatting
*bold phrase* & **char**acter**s**

_italic phrase_ & __char__acter__s__

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

bold phrase & characters

italic phrase & characters

bold italic phrase & characters

Monospace

You can monospace entire phrases, a word, and characters in a word.

Monospace inline formatting
`monospace phrase` & ``char``acter``s``

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

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

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

monospace phrase & characters

monospace bold phrase & characters

monospace italic phrase & characters

monospace bold italic phrase & characters

Highlight

You can highlight entire phrases, a word, and characters in a word.

Highlight inline formatting
Let's #highlight this phrase# and part of th##is##.
Result

Let’s highlight this phrase and part of this.

Lists

Unordered Lists

Basic Unordered List

Basic Unordered List
.Optional Title of List
* Item A
* Item B
* Item C
Optional Title of List

  • Item A

  • Item B

  • Item C

Nested Unordered List

Unordered list with nested levels
* Item A
* Item B
** Item B1
** Item B2
* Item C

  • Item A

  • Item B

    • Item B1

    • Item B2

  • Item C

Maximum nested level
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1

  • level 1

    • level 2

      • level 3

        • level 4

          • level 5

  • level 1

Ordered Lists

Basic Ordered List

Basic Ordered List
.Optional Title of List
. Step 1
. Step 2
. Step 3
Optional Title of List

  1. Step 1

  2. Step 2

  3. Step 3

Nested Ordered List

Ordered list with nested levels
. 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

Maximum nested level
. 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

Admonition styles

An admonition, also known as a notice, helps draw attention to a line or block of text with a special label or icon.

Asciidoctor comes with five built-in styles.

  • NOTE

  • TIP

  • IMPORTANT

  • CAUTION

  • WARNING

Basic admonition

Basic admonitions
CAUTION: Don't stick forks in electric sockets.

TIP: After someone sticks a fork in a socket, you'll need to reset the circuit in the breaker box in the dark and scary basement.

WARNING: Never go into the basement.

IMPORTANT: A monster lives in the basement.

NOTE: If you go into the basement, see if you can find Kenny's orange parka.
Don’t stick forks in electric sockets.
After someone sticks a fork in a socket, you’ll need to reset the circuit in the breaker box in the dark and scary basement.
Never go into the basement.
A monster lives in the basement.
If you go into the basement, see if you can find Kenny’s orange parka.

Complex admonition

Example block masquerading as an admonition
[IMPORTANT]
.Optional Title
====
Use an example block to create an admonition that contains complex content, such as (but not limited to):

* Lists
* Multiple paragraphs
* Source code
* Images
====
Optional Title

Use an example block to create an admonition that contains complex content, such as (but not limited to):

  • Lists

  • Multiple paragraphs

  • Source code

  • Images

A sidebar can be titled and contain any type of content such as source code and images.

Sidebar
.Optional Title of Sidebar
****
Sidebars are used to visually separate short, auxiliary bits of content that supplement the main text.
****
Optional Title of Sidebar

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

Link with label
http://asciidoc.org[AsciiDoc]
Relative link
link:user-guide.html[user guide]
xref:user-guide.adoc[user guide]
File link
link:{site-url}/assets/mydoc.pdf[get the PDF]
Cross reference
See <<_usage>>.

== Usage
Block ID/anchor
[#usage]
== Usage
Inline anchor
. [[step-1]]Download the software

Images

Code/Examples

Literal block

Indented (by 1 or more spaces)
 $ gem install asciidoctor

Indented (by 1 or more spaces)

$ gem install asciidoctor
Delimited
....
$ gem install asciidoctor
....

Delimited

$ gem install asciidoctor

Other examples: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#source-code

Special Characters and Symbols

Special character and symbol replacement is built into Asciidoctor.

During conversion, the characters in the table below are replaced with the appropriate character or Unicode entity. Replacement of special characters and symbols occurs in all inline and block elements except for comments and certain passthroughs. The three special characters, <, >, and &, are always replaced first.

HTML and XML character entities as well as decimal and hexadecimal Unicode code point references are also recognized and replaced.

For example, to produce the § symbol you can use &sect;, &#x00A7;, or &#167;. When the document is processed, the replacements substitution will replace the section symbol reference, regardless of whether it is a character entity reference or a numeric character reference, with &#167;. In turn, &#167; will display as §.

Special character and symbol syntax

Name Syntax Replacement Rendered Notes

Ampersand

 
&

&amp;

&

Apostrophe, curved

 
Sam's

Sam&#8217;s

Sam’s

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

Copyright

 
(C)

&#169;

©

Ellipses

 
...

&#8230;

…​

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

Greater than

 
>

&gt;

>

Left double arrow

 
<=

&#8656;

⇐

Left single arrow

 
<-

&#8592;

←

Less than

 
<

&lt;

Registered

 
(R)

&#174;

®

Right double arrow

 
=>

&#8658;

⇒

Right single arrow

 
->

&#8594;

→

Trademark

 
(TM)

&#8482;

™

User Interface Macros

Asciidoctor has three user interface (UI) macros:

  • Button btn:[]

  • Keyboard kbd:[]

  • Menu menu:[]

The :experimental: attribute must be set in the document header or globally to enable UI macros.

Button

Communicate that a user should press a button with the button macro.

Button UI macro
Press the btn:[Submit] button when you are finished the survey.

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

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

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

Keyboard

Create keyboard shortcuts with the keyboard macro.

Keyboard UI macro
Press kbd:[esc] to exit insert mode.

Use the shortcut kbd:[Ctrl+T] to open a new tab in your browser.

kbd:[Ctrl+Shift+N] will open a new incognito window.
Result

Press kbd:[esc] to exit insert mode.

Use the shortcut kbd:[Ctrl+T] to open a new tab in your browser.

kbd:[Ctrl+Shift+N] will open a new incognito window.

Show readers how to select a menu item with the menu macro.

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

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

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

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