AsciiDoc Admonition Support

AsciiDoc provides five built-in admonition types for drawing attention to specific content. Toph styles each type as a refined callout card with a color-coded left border, tinted background, and icon.

Admonition types 🔗

AsciiDoc defines five admonition types, each for a different purpose.

Note	Use notes to provide additional context or supplementary information that supports the main text.

Tip	Use tips to share best practices, shortcuts, or recommendations that help the reader.

Warning

Use warnings to alert the reader about potential problems or pitfalls they should be aware of.

Caution

Use cautions to flag actions that could cause harm, data loss, or unintended consequences if done carelessly.

Important

Use important admonitions to highlight critical information the reader must not overlook.

Block admonitions 🔗

Admonitions can also span multiple paragraphs using AsciiDoc’s block syntax. This is useful when the message needs more than a single sentence.

Note	Block admonitions use the delimiter syntax with four equals signs. They can contain multiple paragraphs, lists, and other AsciiDoc elements. This is a second paragraph inside the same admonition block.

Tip	When writing documentation, consider which admonition type best fits your message. NOTE for supplementary context TIP for actionable advice WARNING for potential pitfalls CAUTION for risk of harm or data loss IMPORTANT for critical information

Warning

Admonitions should be used sparingly. Overusing them dilutes their impact and makes content harder to scan.

Syntax 🔗

There are two ways to write admonitions in AsciiDoc.

Inline syntax 🔗

The simplest form places the admonition label at the start of a paragraph:

NOTE: This is an inline note admonition.

TIP: This is an inline tip admonition.

Block syntax 🔗

For multi-paragraph admonitions, use the block delimiter:

[NOTE]
====
First paragraph of the admonition.

Second paragraph of the admonition.
====