Inside paragraphs and other text, AsciiDoc applies a fixed series of substitutions that turn marks into formatting, references into values and macros into links and images. Which substitutions apply depends on the block.
Formatting marks
Each mark has a constrained form, single characters around whole
words, and an unconstrained form, doubled, which works anywhere,
even inside a word. A constrained pair works only when a space-like character comes
before it and a space-like character or one of , ; " . ? ! after it, and
the text inside does not start or end with a space.
| Constrained | Unconstrained | Result |
|---|---|---|
*bold* | **b**old | Bold (strong). |
_italic_ | __i__talic | Italic (emphasis). |
`mono` | ``m``ono | Monospace (code). |
#mark# | ##m##ark | Highlighted (marked) text; with a role, [.underline]#text#, a text span with that role and no other formatting. Built-in roles: underline, overline, line-through, nobreak, nowrap, pre-wrap. |
^super^ | – | Superscript; may not contain spaces (use {sp}). |
~sub~ | – | Subscript; may not contain spaces (use {sp}). |
"`double`", '`single`' | – | Curved quotation marks. |
Formatting can be nested (*_bold italic_*); monospace must be the
outermost pair. A backslash before a mark (\*not bold*) stops it being
read.
Passthroughs
| Syntax | Meaning |
|---|---|
+text+, ++text++ | Constrained and unconstrained: no formatting, special characters still escaped for HTML. |
+++text+++ | Raw: output as is, no substitutions. |
pass:[text], pass:q,a[text] | Raw, or with only the listed substitutions applied (comma-separated, no spaces). The only macro processed in the document header by default. |
`+text+` | Literal monospace: monospace with no formatting inside. |
Replacements
| Text | Becomes |
|---|---|
(C), (R), (TM) | ©, ®, ™ |
-- | An em dash, between two word characters, between a word character and the line boundary, or with spaces either side (which become thin spaces) |
... | An ellipsis |
->, =>, <-, <= | Single and double arrows |
' in a word (Sam's) | A typographic apostrophe |
&name;, §, § | HTML and XML character references, output as decimal references; named ones outside the XML five (lt, gt, amp, quot, apos) may fail in non-HTML output |
Inline macros and references
| Syntax | Meaning |
|---|---|
https://example.org, https://example.org[text] | Links; URLs with the schemes http, https, ftp, irc and mailto are recognised on their own, and so are most e-mail addresses. Attributes: id, role, title, window=_blank (or ^ at the end of the text), opts (nofollow, noopener). |
link:path[text] | A link to any target, including relative paths. |
mailto:a@example.org[text], a@example.org | E-mail links; the mailto: form is needed to add attributes. |
<<id>>, <<id,text>>, xref:id[text] | Cross references to an ID in this document; without text the target’s reftext (usually its title) is used. xref:other.adoc#id[text] points into another document. |
[[id]], [#id]#text# | Inline anchors. |
footnote:[text], footnote:name[text], footnote:name[] | A footnote; a named one can be referred to again with empty brackets. |
image:file.png[alt,16] | An inline image (one colon). |
icon:heart[2x] | An icon: from the icon font, or an image, depending on the icons attribute; size applies to font icons. |
kbd:[Ctrl+C], btn:[OK], menu:File[Save As…] | Keys, buttons and menu paths; need the experimental attribute. |
stem:[sqrt(4)], latexmath:[\sqrt{4}], asciimath:[sqrt(4)] | Inline maths; stem uses the notation set by the stem attribute (AsciiMath by default). |
((term)) or indexterm2:[term]; (((primary,secondary,tertiary))) or indexterm:[primary,secondary,tertiary] | Index terms: a flow term appears in the text, a concealed one does not. |
text + at the end of a line | A + after a space at the end of a line forces a line break; [%hardbreaks] keeps all line breaks of a paragraph, and the hardbreaks-option attribute those of the whole document. |
Substitutions
Text is processed in this order. Each step has a name and a letter used in
subs attributes and pass: macros:
| # | Step | Letter | What it does |
|---|---|---|---|
| 1 | specialchars | c | Escapes <, > and &. |
| 2 | quotes | q | Formatting marks. |
| 3 | attributes | a | Attribute references. |
| 4 | replacements | r | Replacements. |
| 5 | macros | m | Inline macros, links and cross references. |
| 6 | post_replacements | p | Line breaks. |
Groups: normal (n, all six, used for most blocks and
inline text), header (special characters, attribute references and the
inline pass macro, used for the header lines and attribute values),
verbatim (v, special characters and callouts, used for
literal, listing and source blocks), pass (nothing, or only special
characters for the + and ++ forms) and none
(comments). The callouts step turns <1> markers in
verbatim blocks into callout numbers. A block’s subs attribute replaces
its set, or changes the default with modifiers: +name appends,
name+ prepends and -name removes a step.
Sources
- AsciiDoc Language Documentation: text formatting – constrained and unconstrained pairs, bold, italic, monospace, highlight, text spans and built-in roles, superscript and subscript, curved quotes, literal monospace
- Inline passthroughs – single, double and triple plus, the
pass:macro and its substitution values - Substitutions – order, groups, special characters, replacements, post replacements, block
subsand incremental modifiers, escaping with a backslash - Autolinks, link macro attributes, mailto, cross references, footnotes, icons and UI macros – the inline macros
- STEM, index and hard line breaks – inline maths, index terms, line breaks