Callout boxes win AI extraction when they declare a type (note, tip, warning, danger, info), open with a one-sentence summary, use ARIA role attributes for accessibility-driven semantics, and remain self-contained without external context. Stripe docs, Mintlify, and Notion converge on this pattern; AI engines lift the callout content as a quotable, attributable block.
TL;DR
Use 5 callout types: note, tip, warning, danger, info. Avoid inventing custom types AI engines do not recognize.
Each callout opens with a one-sentence summary in bold. AI engines extract this as the snippet head.
Add role="note" (or role="alert" for danger/warning) and aria-label to the wrapper element.
Make every callout self-contained — readable without surrounding paragraphs.
Keep callouts short: 1-4 sentences. Long callouts break extraction; for longer content, use a section heading instead.
Why callouts are AEO leverage
Callout boxes (a.k.a. admonitions, info-boxes, notes) are the highest-density-per-pixel AEO format in any documentation system. They are visually distinct, semantically separable, and structurally self-contained. AI engines lift them as standalone snippets, often crediting the source page inline. Stripe, Mintlify, GitHub, and Notion all use this pattern at scale.
The leverage comes from the structural promise a callout makes to the parser: "this block stands on its own; you can quote it without context." When that promise holds, AI engines reward it.
The 5 callout types and when to use each
Note
General commentary, side context, or supplementary information. Use for: prerequisites, related-topic pointers, version-specific notes that are not warnings. ARIA: role="note".
Tip
Non-obvious advice that improves outcomes. Use for: best practices, performance tips, naming conventions. ARIA: role="note" with descriptive aria-label="Tip".
Warning
Non-fatal but important caveats: deprecation notices, behavior surprises, edge cases. ARIA: role="alert" for time-sensitive warnings; otherwise role="note" with aria-label="Warning".
Danger
Fatal or destructive actions: data loss, irreversible operations, security risks. ARIA: role="alert". Color: red.
Info
Neutral metadata: API status, region availability, billing implications. ARIA: role="note".
The 7 rules of extractable callouts
Rule 1: Declare the type explicitly
Use a visible label or icon at the start of the callout: "Note:", "Warning:", "Tip:". Do not rely on color alone — color is not extractable; the textual label is.
Rule 2: Open with a one-sentence summary
The first sentence should encapsulate the entire callout. AI engines lift this sentence as the snippet head. Bold the summary if the design system supports it.
ChatGPT
Claude
Gemini
Perplexity