Using Callouts and Admonitions

Version 2.0 Standard: Premium

Callouts (or Admonitions) are "visual islands" in a sea of text. They break the rhythm of reading and force the user to pay attention to a specific insight.

They are the most powerful tool for increasing Time on Page. Users often skim the intro, then jump straight to the colored boxes.

Part 1 — The Psychology of Color

Docusaurus (and most web frameworks) uses standard semantic colors. Users are trained to react to these colors instinctively.

Type	Color	Emotion	User Reaction
`:::note`	Blue/Gray	Neutral	"Background info." (Low urgency)
`:::tip`	Green	Positive	"A shortcut! Value!" (High urgency)
`:::info`	Blue	Directive	"I should probably know this." (Medium urgency)
`:::warning`	Yellow	Caution	"Wait, stop." (Very high urgency)
`:::danger`	Red	Fear	"This will break something." (Max urgency)

Part 2 — The "Island Strategy" (Placement Workflow)

Do not sprinkle callouts randomly. Use them strategically to manage the user's attention span.

flowchart TD
    A["Drafting Content"] --> B{"Is this point critical?"}
    B -- No --> C["Keep as Body Text"]
    B -- Yes --> D{"Is it a Warning?"}
    D -- Yes --> E["Use Yellow/Red Box\nBEFORE the step"]
    D -- No --> F{"Is it a Shortcut?"}
    F -- Yes --> G["Use Green Box\nAFTER the step"]
    F -- No --> H["Use Blue Box\n(Rarely)"]

The Rules of Placement

Placement: Warnings go before the action. Tips go after the action.
Frequency: Max 1 callout every 2-3 scroll depths. (Too many = Banner Blindness).
Length: A callout should never be longer than 3 sentences. If it is, it's a paragraph, not a callout.

Part 3 — Admonition Templates

Use these patterns to drive engagement.

The Efficiency Tip (Green)
The Trap Warning (Yellow)
The Context Note (Blue)

Goal: Make the user feel smart. Give them a "Pro" shortcut.

Save 30 Minutes

Don't write your metadata manually. Use the "Meta Generator" template to create optimized titles in seconds.

Part 4 — Bad vs. Good Examples

❌ The Wall of Color
✅ The Strategic Island

Introduction

SEO is important.

What to do

You should optimize your titles.

How to do it

Use keywords.

(Why it fails: Callout fatigue. Used for basic text. The user stops seeing them.)

Part 5 — AI Collaboration Guidelines

AI is terrible at callouts. It usually writes 3-paragraph "Notes" that repeat what the body text just said.

The "Gem Extraction" Prompt

Role: Editor Task: Extract "Callout" opportunities from this text. Rules:

Find any risk or error. Wrap it in a :::warning block.

Find any efficiency hack or shortcut. Wrap it in a :::tip block.

Rewrite the callout text to be under 30 words.

Remove the callout content from the main body text (don't duplicate it). Input: [Paste Draft]

Pattern to Fix: The "Duplication Loop"

AI often does this:

"Make sure you save your file periodically.

tip
Save your file often so you don't lose work. :::"

Fix: Delete the body text. Let the callout stand alone.

Part 6 — Output Checklist

Semantic Match: Did I use Yellow for Warning and Green for Tips?
Positioning: Are warnings placed before the dangerous step?
Brevity: Is the callout content under 3-4 sentences?
Frequency: Are there fewer than 3 callouts per 1,000 words? (Rule of thumb).
Value: Does the callout offer new value, or just repeat the text?

Part 1 — The Psychology of Color​

Part 2 — The "Island Strategy" (Placement Workflow)​

The Rules of Placement​

Part 3 — Admonition Templates​

Part 4 — Bad vs. Good Examples​

Part 5 — AI Collaboration Guidelines​

The "Gem Extraction" Prompt​

Pattern to Fix: The "Duplication Loop"​

Part 6 — Output Checklist​