Callout

Give a paragraph visual weight — pull "this is important / this is a warning / this is an insight" out of the flowing text so a reader scanning the page won't miss it.

When to use

✅ You have a passage that's critical for the reader — worth making the eye stop
✅ You want to flag a warning / risk / common pitfall
✅ You want to surface an insight / realization / key observation from the body of an argument
❌ Whole sections in callouts — visual signal devalues; a callout becomes "no callout"
❌ Using callouts for layout / decoration — wrong tool, use Layout grid

Basic syntax

A callout is a standard blockquote with a type marker on the first line: [!TYPE].

> [!INFO]
> This is an informational note.
> Continue across multiple lines with `>` prefix.

> [!WARN]
> This is a warning.

> [!ZEN]
> This is an insight / realization. Rho-native type, for "aha moments".

Renders: a colored highlight block with a side bar, type icon + type name header, and your content below.

All types

Rho supports 3 native types + 5 GitHub-flavored alerts = 8 total.

Rho native (recommended)

Type	Color	Icon	Use
`[!INFO]`	Blue	ℹ️	General information / context / notes
`[!WARN]`	Orange	⚠️	Warning / careful / easy to miss
`[!ZEN]`	Green	🌿	Insight / realization / key observation

GitHub-flavored alerts (compatible)

Type	Color	Use
`[!NOTE]`	Blue	Note (same as INFO; GFM standard)
`[!TIP]`	Green	Practical tip
`[!IMPORTANT]`	Purple	Emphasize a key point
`[!WARNING]`	Yellow	Warning (same as WARN; GFM standard)
`[!CAUTION]`	Red	Serious risk

INFO or NOTE — which to pick? Pick by consistency. If your doc renders mainly on GitHub, use GFM types ([!NOTE] / [!TIP] / etc.) — GitHub web doesn't recognize [!INFO]. If your doc renders mainly in Rho, use INFO / WARN / ZEN — they carry sharper semantics (especially ZEN, which has no GFM equivalent).

Examples

Example 1: simplest note

> [!INFO]
> Rho `.md` files open in any markdown editor.

Renders: blue highlight block with a blue side bar + ℹ️ icon + "INFO" header, your line below.

Example 2: multi-line + inline code

> [!WARN]
> Don't put spaces inside the type marker brackets:
>
> - ✅ Right: `> [!INFO]`
> - ❌ Wrong: `> [! INFO]` or `> [ !INFO ]`
>
> The parser is space-sensitive.

Renders: orange highlight block holding multiple paragraphs (including a list and inline code) inside a single callout frame.

Example 3: ZEN (Rho-only)

> [!ZEN]
> Markdown beat wiki / RTF / docx because of one unbreakable promise:
> **any tool can open it; in the worst case you see plain text — not a broken binary or failed render**.
>
> Rho cannot violate this. Every DSL must have a plain-text fallback.

Renders: green highlight block, 🌿 icon + "ZEN" header. Visually heavier than INFO, less urgent than WARN — a dedicated semantic slot for "insight" content.

Example 4: optional inline title

Some readers support a custom title after the type marker:

> [!WARN] This API is removed in v0.7
> Use the new export dialog instead. See migration guide for details.

Renders: header shows the custom title "This API is removed in v0.7" instead of the default "WARN" label.

Note: inline titles aren't universal in standard GFM. Rho supports them; GitHub partially supports them; Obsidian supports them. For maximum compatibility, put the title on the first body line:
> [!WARN]
> **This API is removed in v0.7**
> Use the export dialog instead...

Plain-text fallback behavior

A callout is pure standard markdown blockquote + a [!TYPE] marker. In readers that don't support callouts, it degrades to:

> [!INFO]
> This is an informational note.
> Continue across multiple lines with > prefix.

→ shows as a regular blockquote with [!INFO] visible — readers still see content and still recognize the "this is an INFO" semantic intent.

Per-reader breakdown:

Reader	Render
Rho	Full highlight block (color bar + icon + header)
GitHub web	Full highlight block (only `[!NOTE]` / `[!TIP]` / `[!IMPORTANT]` / `[!WARNING]` / `[!CAUTION]`; Rho-native types show as `[!INFO]` literal + plain blockquote)
Obsidian	Full highlight block (recognizes a wide callout type vocabulary including INFO / WARN)
VS Code default preview	Plain blockquote + `[!INFO]` literal visible
cat / less / any text editor	Source as plain text

Content stays readable in every case — that's the design promise of plain-text fallback.

Common pitfalls

1. Marker case

> [!info]    ← ⚠️ Some readers don't recognize lowercase
> [!INFO]    ← ✅ Recommended (spec standard)

Type markers should be uppercase. Rho tolerates lowercase; GitHub strictly requires uppercase.

2. Don't break a callout with a blank line

> [!INFO]
> First paragraph.

> Second paragraph.    ← ❌ Blank line separates → second paragraph leaves the callout

Correct way — separate paragraphs with a blank quote line (just >):

> [!INFO]
> First paragraph.
>
> Second paragraph.    ← ✅ Still in the same callout

3. Nested callouts not supported

> [!INFO]
> Outer INFO
> > [!WARN]            ← ❌ Nesting not supported; renders as nested blockquote
> > Inner WARN

If you need to "emphasize a passage inside an INFO," use bold / inline code / a list. Don't nest callouts.

4. Don't ask callout to do layout's job

> [!INFO] Feature A
> Description A

> [!INFO] Feature B
> Description B

> [!INFO] Feature C
> Description C

This is layout work, not callout work. Callouts are for emphasis; side-by-side display is Layout grid + cards.

5. Whole page is callouts

If 80% of a page is callouts, visual weight collapses. Callouts should be sparse and prominent — ~~emphasis on every paragraph equals no emphasis at all~~.