7. Text Formatting

Prev		Next

7.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).
‘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 (see example below).

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 can be prefixed with an attribute list:

Setting the AsciiDoc role attribute will enclose DocBook markup in a phrase element and HTML markup in a span element. For example this AsciiDoc: [role="foo"]'Hello World' generates this DocBook: <phrase role="foo"><emphasis>Hello World</emphasis></phrase> and this HTML: <span class="foo"><em>Hello World</em></span>
You can set the font color, background color and size using the first three positional attribute arguments (HTML outputs only). The first argument is the text color; the second the background color; the third is the font size. Colors are valid CSS colors and the font size is a number which treated as em units. Here are some examples:
```
[red]#Red text#.
[,yellow]*bold text on a yellow background*.
[blue,#b0e0e6]+Monospaced blue text on a light blue background+
[,,2]#Double sized text#.
```

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

7.1.1. Constrained and Unconstrained Quotes

There are actually two types of quotes:

7.1.1.1. Constrained quotes

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

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

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

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

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

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

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

include::addendum.txt[tabsize=2]

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

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

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

&#x278a; &#182;

renders:

➊ ¶

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

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

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