---

Text Formatting

Quoted Text

Words and phrases can be formatted by enclosing inline text with quote characters:

Emphasized text

Word phrases 'enclosed in single quote characters' (acute accents) or _underline characters_ are emphasized.

Strong text

Word phrases *enclosed in asterisk characters* are rendered in a strong font (usually bold).

Monospaced text

Word phrases +enclosed in plus characters+ are rendered in a monospaced font. Word phrases `enclosed in backtick characters` (grave accents) are also rendered in a monospaced font but in this case the enclosed text is rendered literally and is not subject to further expansion (see inline literal passthrough).

‘Single quoted text’

Phrases enclosed with a `single grave accent to the left and a single acute accent to the right' are rendered in single quotation marks.

“Double quoted text”

Phrases enclosed with ``two grave accents to the left and two acute accents to the right'' are rendered in quotation marks.

Unquoted text

Placing #hashes around text# does nothing, it is a mechanism to allow inline attributes to be applied to otherwise unformatted text.

New quote types can be defined by editing asciidoc(1) configuration files. See the Configuration Files section for details.

Quoted text behavior

• Quoting cannot be overlapped.

• Different quoting types can be nested.

• To suppress quoted text formatting place a backslash character immediately in front of the leading quote character(s). In the case of ambiguity between escaped and non-escaped text you will need to escape both leading and trailing quotes, in the case of multi-character quotes you may even need to escape individual characters.

Quoted text attributes

Quoted text can be prefixed with an attribute list. The first positional attribute (role attribute) is translated by AsciiDoc to an HTML span element class attribute or a DocBook phrase element role attribute.

DocBook XSL Stylesheets translate DocBook phrase elements with role attributes to corresponding HTML span elements with the same class attributes; CSS can then be used to style the generated HTML. Thus CSS styling can be applied to both DocBook and AsciiDoc generated HTML outputs. You can also specify multiple class names separated by spaces.

CSS rules for text color, text background color, text size and text decorators are included in the distributed AsciiDoc CSS files and are used in conjunction with AsciiDoc xhtml11, html5 and docbook outputs. The CSS class names are:

• <color> (text foreground color).

• <color>-background (text background color).

• big and small (text size).

• underline, overline and line-through (strike through) text decorators.

Where <color> can be any of the sixteen HTML color names. Examples:

[red]#Obvious# and [big red yellow-background]*very obvious*.

[underline]#Underline text#, [overline]#overline text# and
[blue line-through]*bold blue and line-through*.

is rendered as:

Obvious and very obvious.

Underline text, overline text and bold blue and line-through.

Note

Color and text decorator attributes are rendered for XHTML and HTML 5 outputs using CSS stylesheets. The mechanism to implement color and text decorator attributes is provided for DocBook toolchains via the DocBook phrase element role attribute, but the actual rendering is toolchain specific and is not part of the AsciiDoc distribution.

Constrained and Unconstrained Quotes

There are actually two types of quotes:

Constrained quotes

Quoted must be bounded by white space or commonly adjoining punctuation characters. These are the most commonly used type of quote.

Unconstrained quotes

Unconstrained quotes have no boundary constraints and can be placed anywhere within inline text. For consistency and to make them easier to remember unconstrained quotes are double-ups of the _, *, + and # constrained quotes:

__unconstrained emphasized text__
**unconstrained strong text**
++unconstrained monospaced text++
##unconstrained unquoted text##

The following example emboldens the letter F:

**F**ile Open...

Superscripts and Subscripts

Put ^carets on either^ side of the text to be superscripted, put ~tildes on either side~ of text to be subscripted. For example, the following line:

e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
and ~some sub text~

Is rendered like:

e^πi+1 = 0. H₂O and x¹⁰. Some ^{super text} and _{some sub text}

Superscripts and subscripts are implemented as unconstrained quotes and they can be escaped with a leading backslash and prefixed with with an attribute list.

Line Breaks

A plus character preceded by at least one space character at the end of a non-blank line forces a line break. It generates a line break (br) tag for HTML outputs and a custom XML asciidoc-br processing instruction for DocBook outputs. The asciidoc-br processing instruction is handled by a2x(1).

Page Breaks

A line of three or more less-than (<<<) characters will generate a hard page break in DocBook and printed HTML outputs. It uses the CSS page-break-after property for HTML outputs and a custom XML asciidoc-pagebreak processing instruction for DocBook outputs. The asciidoc-pagebreak processing instruction is handled by a2x(1). Hard page breaks are sometimes handy but as a general rule you should let your page processor generate page breaks for you.

Rulers

A line of three or more apostrophe characters will generate a ruler line. It generates a ruler (hr) tag for HTML outputs and a custom XML asciidoc-hr processing instruction for DocBook outputs. The asciidoc-hr processing instruction is handled by a2x(1).

Tabs

By default tab characters input files will translated to 8 spaces. Tab expansion is set with the tabsize entry in the configuration file [miscellaneous] section and can be overridden in included files by setting a tabsize attribute in the include macro’s attribute list. For example:

include::addendum.txt[tabsize=2]

The tab size can also be set using the attribute command-line option, for example --attribute tabsize=4

Replacements

The following replacements are defined in the default AsciiDoc configuration:

(C) copyright, (TM) trademark, (R) registered trademark,
-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
double arrow, <= left double arrow.

Which are rendered as:

© copyright, ™ trademark, ® registered trademark, — em dash, … ellipsis, → right arrow, ← left arrow, ⇒ right double arrow, ⇐ left double arrow.

You can also include arbitrary entity references in the AsciiDoc source. Examples:

➊ ¶

renders:

➊ ¶

To render a replacement literally escape it with a leading back-slash.

The Configuration Files section explains how to configure your own replacements.

Special Words

Words defined in [specialwords] configuration file sections are automatically marked up without having to be explicitly notated.

The Configuration Files section explains how to add and replace special words.

---

Titles

Document and section titles can be in either of two formats:

Two line titles

A two line title consists of a title line, starting hard against the left margin, and an underline. Section underlines consist a repeated character pairs spanning the width of the preceding title (give or take up to two characters):

The default title underlines for each of the document levels are:

Level 0 (top level):     ======================
Level 1:                 ----------------------
Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level):  ++++++++++++++++++++++

Examples:

Level One Section Title
-----------------------

Level 2 Subsection Title
~~~~~~~~~~~~~~~~~~~~~~~~

One line titles

One line titles consist of a single line delimited on either side by one or more equals characters (the number of equals characters corresponds to the section level minus one). Here are some examples:

= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====

Note	One or more spaces must fall between the title and the delimiters. The trailing title delimiter is optional. The one-line title syntax can be changed by editing the configuration file [titles] section sect0…sect4 entries.

Floating titles

Setting the title’s first positional attribute or style attribute to float generates a free-floating title. A free-floating title is rendered just like a normal section title but is not formally associated with a text body and is not part of the regular section hierarchy so the normal ordering rules do not apply. Floating titles can also be used in contexts where section titles are illegal: for example sidebar and admonition blocks. Example:

[float]
The second day
~~~~~~~~~~~~~~

Floating titles do not appear in a document’s table of contents.

---

Block Titles

A BlockTitle element is a single line beginning with a period followed by the title text. A BlockTitle is applied to the immediately following Paragraph, DelimitedBlock, List, Table or BlockMacro. For example:

.Notes
- Note 1.
- Note 2.

is rendered as:

Notes

• Note 1.

• Note 2.

---

BlockId Element

A BlockId is a single line block element containing a unique identifier enclosed in double square brackets. It is used to assign an identifier to the ensuing block element. For example:

[[chapter-titles]]
Chapter titles can be ...

The preceding example identifies the ensuing paragraph so it can be referenced from other locations, for example with <<chapter-titles,chapter titles>>.

BlockId elements can be applied to Title, Paragraph, List, DelimitedBlock, Table and BlockMacro elements. The BlockId element sets the {id} attribute for substitution in the subsequent block’s markup template. If a second positional argument is supplied it sets the {reftext} attribute which is used to set the DocBook xreflabel attribute.

The BlockId element has the same syntax and serves the same function to the anchor inline macro.

---

AttributeList Element

An AttributeList block element is an attribute list on a line by itself:

• AttributeList attributes are only applied to the immediately following block element — the attributes are made available to the block’s markup template.

• Multiple contiguous AttributeList elements are additively combined in the order they appear.

• The first positional attribute in the list is often used to specify the ensuing element’s style.

Attribute value substitution

By default, only substitutions that take place inside attribute list values are attribute references, this is because not all attributes are destined to be marked up and rendered as text (for example the table cols attribute). To perform normal inline text substitutions (special characters, quotes, macros, replacements) on an attribute value you need to enclose it in single quotes. In the following quote block the second attribute value in the AttributeList is quoted to ensure the http macro is expanded to a hyperlink.

[quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]'] _____________________________________________________________________ Sir, a woman's preaching is like a dog's walking on his hind legs. It is not done well; but you are surprised to find it done at all. _____________________________________________________________________

Common attributes

Most block elements support the following attributes:

Name	Backends	Description
id	html4, html5, xhtml11, docbook	Unique identifier typically serve as link targets. Can also be set by the BlockId element.
role	html4, html5, xhtml11, docbook	Role contains a string used to classify or subclassify an element and can be applied to AsciiDoc block elements. The AsciiDoc role attribute is translated to the role attribute in DocBook outputs and is included in the class attribute in HTML outputs, in this respect it behaves like the quoted text role attribute. DocBook XSL Stylesheets translate DocBook role attributes to HTML class attributes; CSS can then be used to style the generated HTML.
reftext	docbook	reftext is used to set the DocBook xreflabel attribute. The reftext attribute can an also be set by the BlockId element.

---

Paragraphs

Paragraphs are blocks of text terminated by a blank line, the end of file, or the start of a delimited block or a list. There are three paragraph syntaxes: normal, indented (literal) and admonition which are rendered, by default, with the corresponding paragraph style.

Each syntax has a default style, but you can explicitly apply any paragraph style to any paragraph syntax. You can also apply delimited block styles to single paragraphs.

The built-in paragraph styles are: normal, literal, verse, quote, listing, TIP, NOTE, IMPORTANT, WARNING, CAUTION, abstract, partintro, comment, example, sidebar, source, music, latex, graphviz.

normal paragraph syntax

Normal paragraph syntax consists of one or more non-blank lines of text. The first line must start hard against the left margin (no intervening white space). The default processing expectation is that of a normal paragraph of text.

literal paragraph syntax

Literal paragraphs are rendered verbatim in a monospaced font without any distinguishing background or border. By default there is no text formatting or substitutions within Literal paragraphs apart from Special Characters and Callouts.

The literal style is applied implicitly to indented paragraphs i.e. where the first line of the paragraph is indented by one or more space or tab characters. For example:

Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui.

Renders:

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

Note	Because lists can be indented it’s possible for your indented paragraph to be misinterpreted as a list — in situations like this apply the literal style to a normal paragraph.

Instead of using a paragraph indent you could apply the literal style explicitly, for example:

[literal] Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui.

Renders:

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

quote and verse paragraph styles

The optional attribution and citetitle attributes (positional attributes 2 and 3) specify the author and source respectively.

The verse style retains the line breaks, for example:

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

Which is rendered as:

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

from Auguries of Innocence
— William Blake

The quote style flows the text at left and right margins, for example:

[quote, Bertrand Russell, The World of Mathematics (1956)] A good notation has subtlety and suggestiveness which at times makes it almost seem like a live teacher.

Which is rendered as:

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

The World of Mathematics (1956)
— Bertrand Russell

Admonition Paragraphs

TIP, NOTE, IMPORTANT, WARNING and CAUTION admonishment paragraph styles are generated by placing NOTE:, TIP:, IMPORTANT:, WARNING: or CAUTION: as the first word of the paragraph. For example:

NOTE: This is an example note.

Alternatively, you can specify the paragraph admonition style explicitly using an AttributeList element. For example:

[NOTE]
This is an example note.

Renders:

Note	This is an example note.

Tip	If your admonition requires more than a single paragraph use an admonition block instead.

Admonition Icons and Captions

Note	Admonition customization with icons, iconsdir, icon and caption attributes does not apply when generating DocBook output. If you are going the DocBook route then the a2x(1) --no-icons and --icons-dir options can be used to set the appropriate XSL Stylesheets parameters.

By default the asciidoc(1) HTML backends generate text captions instead of admonition icon image links. To generate links to icon images define the icons attribute, for example using the -a icons command-line option.

The iconsdir attribute sets the location of linked icon images.

You can override the default icon image using the icon attribute to specify the path of the linked image. For example:

[icon="./images/icons/wink.png"]
NOTE: What lovely war.

Use the caption attribute to customize the admonition captions (not applicable to docbook backend). The following example suppresses the icon image and customizes the caption of a NOTE admonition (undefining the icons attribute with icons=None is only necessary if admonition icons have been enabled):

[icons=None, caption="My Special Note"]
NOTE: This is my special note.

This subsection also applies to Admonition Blocks.