Chapter 10. Text Formatting

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

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


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.

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

10.2. 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^&#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
and ~some sub text~

Is rendered like:

eπi+1 = 0. H2O and x10. 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.

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

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

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

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


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

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

&#x278a; &#182;


➊ ¶

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

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

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