Text Formatting and Punctuation
Just as we emphasize certain words and phrases when we speak, we emphasize words and phrases in text using formatting and punctuation. AsciiDoc provides an assortment of formatting marks for applying visual emphasis and typographic punctuation to your document. You can build on these basic formatting marks using built-in and user-defined roles. This page covers the formatting marks that AsciiDoc provides and the rules for applying and customizing them.
A formatting mark is a symbolic character, such as
~, that indicates the inline style you want Asciidoctor to apply to the text.
Formatting marks come in pairs.
A formatting pair consists of an identical opening mark and closing mark that encloses the text you want to style.
The opening mark specifies where you want the style to start. The closing mark specifies where you want the style to end.
A formatting pair is defined as either constrained or unconstrained, depending on where it’s allowed to be applied. An unconstrained pair can be applied anywhere, whereas the application of a constrained pair is more limited.
When a blank space directly precedes the text to format, and a blank space or punctuation mark (
!) directly follows the text, a constrained formatting pair can be used.
A constrained pair uses a single opening mark and a single closing mark to enclose the text to be styled (e.g.,
For example, you use this form to format a word that stands alone,
That is *strong* stuff!
to format a sequence of words,
That is *really strong* stuff!
or to format a word adjacent to punctuation, like an exclamation mark.
This stuff is *strong*!
As you can see, the constrained pair offers a more succinct markup at the tradeoff of having more limited (constrained) use. However, it should suffice in most cases, so the abbreviated markup is a benefit. You can think of a constrained pair as being a weaker markup than an unconstrained pair.
When a blank space does not precede the text to format, or a blank space or punctuation mark (
!) does not directly follow the text, or the text does not start or end with a word character, a unconstrained formatting pair must be used.
An unconstrained pair uses a double opening mark and a double closing mark to enclose the text to be styled (e.g.,
For example, you’d use an unconstrained pair to format just one or a few letters in a word.
She spells her name with an "`h`", as in Sara**h**.
The unconstrained pair provides a more brute force approach to formatting at the tradeoff of being more verbose. You’ll typically switch to an unconstrained pair when a constrained pair doesn’t do the trick. See When should I use an unconstrained pair? for more examples of when to use an unconstrained pair.
AsciiDoc provides six inline text styles and one punctuation style that are applied solely with formatting marks.
Text that is bold will stand out against the regular, surrounding text due to the application of a thicker and/or darker font. Bold is useful when the text needs to catch the attention of a person visually scanning a page. The formatting mark for bold is an asterisk (
Text is often italicized in order to stress a word or phrase, quote a speaker, or introduce a term. Italic type slants slightly to the right, and depending on the font, may have cursive swashes and flourishes. The formatting mark for italic is an underscore (
Technical content often requires text to be styled in a way that indicates a command or source code. Such text is usually emphasized using a fixed-width (i.e., monospace) font. The formatting mark for monospace is a backtick (
Another way to draw attention to text is to highlight it. This semantic style is used for reference or notation purposes, or to mark the importance of a key subject or point. The formatting mark for highlight is a hash (
- Subscript and superscript
Subscript and superscript text is common in mathematical expressions and chemical formulas. The formatting mark for subscript is a tilde (
~). The formatting mark for superscript is a caret (
- Curved quotation marks and apostrophes
By default, Asciidoctor uses straight quotation marks and apostrophes. They can be changed to curved using the backtick (
`) formatting mark.
When Asciidoctor processes text enclosed by inline formatting syntax, the marks are replaced by the corresponding HTML or XML tags, depending on your backend, during the quotes substitution step. You can control when inline formatting is applied to inline text, macros, or blocks with the quotes substitution value.