19. Text Formatting

Just as we emphasize certain words and phrases when we speak, we can emphasize them in text with formatting. This formatting, such as bold or monospace, is indicated by surrounding letters, words, or phrases with simple markup. When Asciidoctor processes text enclosed by formatting markup, the markup is replaced by the corresponding HTML or XML tags, depending on your backend, during the quotes substitution phase.

Text formatting versus quotes

The original AsciiDoc processor calls this markup and its related features quotes, quotes substitutions, and quoted text. However, in the Asciidoctor documentation, we refer to the text formatting markup as, you guessed it, text formatting. When you need to control when text formatting is applied to certain blocks, the substitution attribute is still named quotes, but we’re considering changing this to a more semantic name in a future Asciidoctor version.

Continue reading to learn how to format letters, words or phrases with the following styles:

  • bold

  • italic

  • curved (smart) quotation marks and apostrophes

  • subscript and superscript

  • monospace

  • highlighted, built-in and custom CSS styles

You may not always want these symbols to indicate text formatting. In those cases, you’ll need to use additional markup to escape the text formatting markup.

19.1. Bold and Italic

The two most common ways of emphasizing a word is to format it as bold or italic.

To apply bold styling to a word or phrase, place an asterisk (*) at the beginning and end of the text you wish to format. To bold one or more letters within a string of text, place two asterisks (**) before and after the letter(s).

Similarly, words and characters within a word are italicized using one (_) or two (__) underscores, respectively. When you want to bold and italicize text, the bold markup must be the outermost markup.

Bold and italic text formatting syntax
_To tame_ the wild wolpertingers we needed to build a *charm*.
But **u**ltimate victory could only be won if we divined the *_true name_* of the __war__lock.
Result: bold and italic text

To tame the wild wolpertingers we needed to build a charm. But ultimate victory could only be won if we divined the true name of the warlock.

19.2. Quotation Marks and Apostrophes

Single and double quotation marks are not rendered as curved quotation marks (also known as smart, curly, typographic or book quotation marks). When entered using the ' and " key, Asciidoctor outputs straight (dumb, vertical, typewriter) quotation marks. However, by creating a set of backticks (`) contained within a set of single quotes (') or double quotes ("), you can tell Asciidoctor where to output curved quotation marks.

Single and double curved quotation marks syntax
"`What kind of charm?`" Lazarus asked. "`An odoriferous one or a mineral one?`" (1)

Kizmet shrugged. "`The note from Olaf's desk says '`wormwood and licorice,`' but these could be normal groceries for werewolves.`" (2)
1 To output double curved quotes, enclose a word or phrase in a set of double quotes (") and a set of backticks (`).
2 To output single curved quotes, enclose a word or phrase in a set of single quotes (') and a set of backticks (`). In this example, the phrase wormwood and licorice should be enclosed in curved single quotes when the document is rendered.
Rendered curved quotation marks

“What kind of charm?” Lazarus asked. “An odoriferous one or a mineral one?”

Kizmet shrugged. “The note from Olaf’s desk says ‘wormwood and licorice,’ but these could be normal groceries for werewolves.”

When entered with the ' key, Asciidoctor renders an apostrophe that is directly preceded and followed by a character, such as in contractions and possessive singular forms, as a curved apostrophe. This inconsistent handling of apostrophes and quotation marks is a hold over from the original AsciiDoc processor. An apostrophe directly bounded by two characters is processed during the replacements substitution phase, not the quotes phase. This is why an apostrophe directly followed by white space, such as the possessive plural form, is not curved by default.

To render an apostrophe as curved when it is not bound by two characters, mark it as you would a single curved quote.

Curved apostrophe syntax
Olaf had been with the company since the `'60s.
His desk overflowed with heaps of paper, apple cores and squeaky toys.
We couldn't find Olaf's keyboard.
The state of his desk was replicated, in triplicate, across all of the werewolves`' desks.

In the rendered output, note that the plural possessive apostrophe, seen trailing werewolves, is curved, as is the omission apostrophe before 60s.

Rendered apostrophes

Olaf had been with the company since the ’60s. His desk overflowed with heaps of paper, apple cores and squeaky toys. We couldn’t find Olaf’s keyboard. The state of his desk was replicated, in triplicate, across all of the werewolves’ desks.

If you don’t want an apostrophe that is bound by two characters to be rendered as curved, escape it by preceding it with a backslash (\). The preventing substitutions and passthrough sections detail additional ways to prevent punctuation substitutions.

Olaf\'s desk ...
Rendered escaped apostrophe

Olaf's desk …​

In order to make a possessive, monospaced phrase, you need to switch to unconstrained formatting and use an explicit typographic apostrophe.

``npm```'s job is to manage the dependencies for your application.
Rendered possessive, monospaced phrase

npm’s job is to manage the dependencies for your application.

The same goes if the monospaced phrase ends in an “s”.

This ``class```' static methods make it easy to operate on files and directories.
Rendered possessive, monospaced phrase that ends in an “s”

This class’ static methods make it easy to operate on files and directories.

Alternately, you could encode the typographic apostrophe directly in the AsciiDoc source to get the same result without the need to use unconstrained formatting.

The `class`’ static methods make it easy to operate on files and directories.

19.3. Subscript and Superscript

Subscript and superscript text is common in mathematical expressions and chemical formulas. When rendered, the size of subscripted and superscripted text is reduced. Subscripted text is placed at the baseline and superscripted text above the baseline. The size and precise placement of the text depends on the font and other stylesheet parameters applied to the converted document.

Text is subscripted when you enclose it in a set of tildes (~) and superscripted with a set of carets (^)

Subscript

One tilde (~) on either side of a word or phrase makes it subscript.

Superscript

One caret (^) on either side of a word or phrase makes it superscript.

"`Well the H~2~O formula written on their whiteboard could be part of a shopping list, but I don't think the local bodega sells E=mc^2^,`" Lazarus replied.

“Well the H2O formula written on their whiteboard could be part of a shopping list, but I don’t think the local bodega sells E=mc2,” Lazarus replied.

You can write and render equations and formulas in AsciiDoc documents using MathJax.

19.4. Monospace

In AsciiDoc, a span of text enclosed in a single set of backtick (`) characters is displayed using a fixed-width (i.e., monospaced) font. Monospace text formatting is typically used to represent text shown in computer terminals or code editors (often referred to as a codespan).

Monospaced text can be bold and italicized, as long as the markup sets are entered in the right order. The monospace markup must be the outermost set, then the bold set, and the italic markup must always be the innermost set.

As with other types of text formatting, if the text is bounded by characters on either side, it must be enclosed in a double set of backtick characters (``) in order for the formatting to be applied.

Here’s an example:

"`Wait!`" Indigo plucked a small vial from her desk's top drawer and held it toward us.
The vial's label read: `E=mc^2^`; the `_E_` represents _energy_, but also pure _genius!_
Rendered monospace formatted text

“Wait!” Indigo plucked a small vial from her desk’s top drawer and held it toward us. The vial’s label read: E=mc2; the E represents energy, but also pure genius!

19.4.1. Literal Monospace

Unlike other markup languages, monospaced text in AsciiDoc is not synonymous with literal text. Instead, it gets interpreted just like normal text. In other words, it’s subject to text substitutions.

This might be surprising at first. But there’s good reason for this difference. In AsciiDoc, you can take advantage of attribute references and inline macros inside of monospaced text span. The drawback, of course, is that you have to be careful to escape these special characters if you intend to output them literally.

One way to prevent the processor from interpreting special characters in monospaced text is to escape them using backslash characters, just as you would with normal text. However, escaping individual occurrences that way can be tedious. That’s why AsciiDoc offers a special type of monospace formatting called the literal monospace.

To make a true literal codespan in AsciiDoc, you must enclose the monospaced text in a passthrough. Rather than using a single set of backtick characters, you’ll use the combination of the backtick and plus characters, where the plus characters fall on the inside of the backtick characters (e.g., `+text+`). The plus characters are a shorthand for the pass:c[] enclosure.

Here’s an example that contains literal, monospaced text.

You can reference the value of a document attribute using the syntax `+{name}+`, where `name` is the attribute name.

This shorthand syntax can accommodate most of the literal monospace cases. The main exception is when the text itself contains plus characters. To avoid confusing the processor, you’ll need to switch to using the more formal passthrough macro to handle these cases.

Here’s an example of literal, monospaced text that contains plus characters.

`pass:[++]` is the increment operator in C.

Passthroughs are a general purpose utility in AsciiDoc. You can learn about the various passthrough options in Passthrough Macros.

19.5. Custom Styling With Attributes

When text is enclosed in a set of single or double hash symbols (#), and no style is assigned to it, the text will be rendered as highlighted text (text wrapped in <mark>).

Highlighted style syntax
Werewolves are #allergic to cinnamon#.
Highlighted text HTML output
<mark>mark element</mark>
Rendered highlighted text

Werewolves are allergic to cinnamon.

Additionally, text marked with hash symbols can be assigned built-in styles, such as big and green.

Built-in CSS class syntax
Do werewolves believe in [small]#small print#? (1)

[big]##O##nce upon an infinite loop.
1 The first positional attribute is treated as a role. You can assign it a custom or built-in CSS class.
Rendered CSS class styled text

Do werewolves believe in small print?

Once upon an infinite loop.

You can format text with custom styles that you define as well.

Custom CSS class syntax
Type the word [.userinput]#asciidoctor# into the search bar.

When converted to HTML, the word asciidoctor is wrapped in <span> tags and the role userinput is used as the element’s CSS class.

HTML output
<span class="userinput">asciidoctor</span>