Callouts & Alerts

Draw attention to important information with visually distinct callout boxes. Documentation.AI's callout components help you highlight tips, warnings, errors, and other critical information.

Basic Callout Types

Info callouts

Use info callouts for helpful context, explanations, or additional details:

<Callout kind="info">
  **Getting started**: New to our platform? Check out our quickstart guide to set up your account in under 10 minutes.
</Callout>

<Callout kind="info">
  The API rate limit is 1000 requests per hour per API key. Contact support if you need higher limits for production use.
</Callout>

Tip callouts

Share helpful tips, best practices, and recommendations:

<Callout kind="tip">
  **Pro tip**: Store sensitive configuration in environment variables rather than hardcoding values.
</Callout>

<Callout kind="tip">
  Enable browser notifications to get real-time updates when team members comment on your tasks or when deadlines are approaching.
</Callout>

Success callouts

Celebrate achievements, confirm successful operations, or highlight positive outcomes:

<Callout kind="success">
  **Success!** Your setup is complete. You can now start using the platform.
</Callout>

<Callout kind="success">
  **Integration complete**: Your GitHub repository is now connected. Pull requests will automatically create tasks in your project.
</Callout>

Alert callouts

Use alert callouts for important warnings, cautions, or things users should pay attention to:

<Callout kind="alert">
  **Important**: Changes to your configuration may affect existing integrations.
</Callout>

<Callout kind="alert">
  **Breaking change in v2.0**: API function signatures have been updated. Review the migration guide.
</Callout>

Danger callouts

Reserve danger callouts for critical warnings about destructive actions or serious issues:

<Callout kind="danger">
  **Warning**: Destructive operations cannot be undone. Make sure you have backups.
</Callout>

<Callout kind="danger">
  **Security alert**: Keep credentials secure and never expose them in code repositories.
</Callout>

Advanced Callout Usage

Rich content callouts

Callouts can contain any markdown content including lists, code, and links:

<Callout kind="info">
  **Development setup example**:
  
  1. Install dependencies
  2. Configure environment variables  
  3. Start the development server
  4. Open your browser to localhost:3000
  
  Full setup instructions are available in our guide.
</Callout>

Multi-paragraph callouts

Use callouts for longer explanations that span multiple paragraphs:

Nested callouts (use sparingly)

In rare cases, you might need to nest callouts for complex information hierarchies:

Callout Content Patterns

Version and compatibility information

Prerequisites and requirements

Error troubleshooting

Migration and upgrade notices

Feature announcements

Callout Best Practices

When to use each type

Writing effective callout content

Do's:

• ✅ Start with a clear heading that summarizes the main point
• ✅ Use action-oriented language for things users need to do
• ✅ Include specific examples when explaining concepts
• ✅ Provide next steps or links for users who want more information
• ✅ Keep content scannable with bullets, short paragraphs, and formatting

Don'ts:

• ❌ Overuse callouts - too many reduces their impact
• ❌ Use danger callouts for minor issues - save them for truly critical warnings
• ❌ Bury important information in long callout text
• ❌ Use vague language like "be careful" without explaining why
• ❌ Skip the heading - readers scan callouts quickly and need context

Callout placement strategy

Strategic placement:

• Beginning of sections - Set expectations or provide context
• Before code examples - Explain what the code does or prerequisites
• After instructions - Confirm success or provide troubleshooting
• End of sections - Summarize key points or provide next steps

Avoid placing callouts:

• In the middle of step-by-step instructions (breaks flow)
• Too close together (creates visual noise)
• For information better suited to regular text

Callout Accessibility

Screen reader considerations

Callouts are marked up with proper ARIA labels to ensure they're accessible:

• Info callouts: Marked as informational content
• Tip callouts: Marked as helpful hints
• Success callouts: Marked as positive status messages
• Alert callouts: Marked as important warnings
• Danger callouts: Marked as critical alerts that demand attention

Visual accessibility

• Color coding: Each callout type uses distinct colors that meet WCAG contrast requirements
• Icons: Visual icons supplement color coding for users with color blindness
• Typography: Clear hierarchy and readable font sizes
• Focus states: Keyboard navigation support with visible focus indicators

Integration with Other Components

Callouts with code examples

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 20,  // Maximum connections
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
});

Callouts with expandable content

What's next?

Master more component types:

• Images & Media - Add visual elements to enhance callouts
• Tables & Lists - Organize information within callouts
• Expandables & Tabs - Create interactive callout content
• Code Examples - Combine callouts with code for better documentation