Enhanced Content with Markdown Callouts

Overview

XenT now supports GitHub-style callouts through the powerful @r4ai/remark-callout plugin. Create professional-looking information boxes, warnings, and tips that automatically adapt to your chosen theme.

Quick Start

Use this simple syntax to create callouts in your markdown:

> [!note] Remember This
> This is an important note that readers should pay attention to.

> [!warning] Heads Up!
> Be careful when making these changes to avoid breaking your setup.

> [!tip] Pro Tip
> Here's a helpful suggestion to improve your workflow.

For collapsible callouts, add a + after the type:

> [!tip]+ Expandable Content
> This callout can be collapsed and expanded by clicking the title.
> Perfect for optional details or advanced information.

Available Callout Types

Information & Documentation

Note - General information and reminders

Configuration Files

XenT uses a configuration system. Edit user.config.ts in your project root for customizations.

Info - Neutral informational content

Theme Integration

Callouts automatically inherit your theme’s color scheme and design tokens for perfect visual consistency.

Abstract/Summary/TLDR - Key takeaways

Key Concepts

Callouts support multiple types, automatic theming, responsive design, and seamless content integration.

Actions & Tasks

Todo - Action items and tasks

Setup Steps

  1. Install the remark-callout plugin
  2. Configure it in your Astro config
  3. Add CSS styles to match your theme

Tip - Helpful suggestions

Performance Boost

Use callouts sparingly for maximum impact. Too many can overwhelm readers and reduce their effectiveness.

Status & Feedback

Success - Positive outcomes and confirmations

Installation Complete

The callout feature is now active and ready to use in your posts!

Warning - Cautions and important notices

Breaking Changes

This feature requires Astro’s markdown processing. Ensure your content collections are properly configured.

Error/Danger - Critical issues and problems

Common Mistakes

Don’t forget the space after > and before [!type]. Missing spaces will prevent proper rendering.

Communication

Quote - Quotations and references

Design Philosophy

“Great design is not just what it looks like—great design is how it works.” - Steve Jobs

Advanced Usage

Collapsible Callouts

Create expandable callouts using the + syntax for content that users can toggle:

> [!tip]+ Performance Best Practices
> Here are advanced tips that you can expand when needed:
>
> 1. Use callouts strategically, not in every paragraph
> 2. Choose the right type for your content's urgency level
> 3. Keep titles concise but descriptive
Performance Best Practices

Here are advanced tips that you can expand when needed:

  1. Use callouts strategically, not in every paragraph
  2. Choose the right type for your content’s urgency level
  3. Keep titles concise but descriptive

Collapsible Features:

  • Click the title to expand/collapse content
  • Smooth animations with rotating chevron indicator
  • Maintains all standard callout styling and theming
  • Fully keyboard accessible with proper focus states

Nested Callouts

Callouts can be nested inside other callouts for complex information hierarchies:

Advanced Configuration

Here are advanced configuration options:

Breaking Changes

Be careful with these settings as they can break your site.

Performance Tips

These optimizations can improve your build times:

  • Enable incremental builds
  • Use build caching
  • Optimize image processing

Nested Content

Callouts support rich markdown content including code blocks, lists, and links:

Code Example

Here’s how to configure the plugin in your astro.config.ts:

import remarkCallout from '@r4ai/remark-callout';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkCallout],
  },
});
  • Supports syntax highlighting
  • Works with existing remark plugins
  • Integrates seamlessly with Astro

Multiple Paragraphs

Content Organization

You can include multiple paragraphs in callouts to provide comprehensive information.

This second paragraph demonstrates how content flows naturally within the callout container.

Use this for detailed explanations that need more space.

Theme Integration

Automatic Color Adaptation

XenT’s callout implementation automatically adapts to your chosen theme:

  • Status Colors: Uses semantic color tokens for consistent meaning
  • Surface Integration: Matches card and overlay surfaces
  • Text Contrast: Ensures proper readability across all themes
  • Border Emphasis: Provides clear visual hierarchy

Responsive Design

Callouts are fully responsive and mobile-optimized:

  • Reduced padding on mobile devices
  • Scalable icon sizes
  • Proper touch targets
  • Readable typography at all screen sizes

Best Practices

Content Strategy

Use Sparingly - Callouts are most effective when used strategically, not throughout every paragraph.

Clear Hierarchy - Choose the right type for your content’s purpose and urgency level.

Consistent Voice - Match your callout tone to your overall content style.

Technical Guidelines

Performance Considerations

While callouts are lightweight, avoid overusing them in long-form content as they can create visual fatigue.

Accessibility - Icons and colors provide visual cues, but ensure your text content is self-explanatory.

Print Compatibility - Callouts include print-friendly styles for documentation that needs hard copies.

Implementation Details

Plugin Integration

The callout feature uses the @r4ai/remark-callout plugin, which:

  • Processes markdown at build time
  • Generates semantic HTML with data attributes
  • Supports all standard callout types
  • Works with existing remark plugin ecosystem

CSS Architecture

XenT’s callout styles follow the theme’s design token system:

[data-callout] {
  /* Uses semantic tokens for consistent theming */
  background: var(--callout-bg, var(--surface-card));
  color: var(--callout-text, var(--text-primary));
  border-left: 0.25rem solid var(--callout-accent);
}

Browser Support

Callouts work in all modern browsers and gracefully degrade in older ones:

  • CSS custom properties with fallbacks
  • Semantic HTML structure
  • Progressive enhancement approach

Troubleshooting

Common Issues

Callouts Not Rendering

Missing Plugin Configuration

Ensure remarkCallout is added to your remarkPlugins array in astro.config.ts.

Styling Inconsistencies

CSS Import Order

Verify that callouts.css is imported in your global stylesheet after theme imports.

Mobile Display Problems

Responsive Testing

Test callouts on various screen sizes to ensure proper mobile rendering and readability.

Future Enhancements

XenT’s callout system is designed for extensibility:

  • Custom callout types
  • Icon customization
  • Animation support
  • Interactive variants
Ready to Use

Callouts are now integrated into your XenT theme and ready to enhance your content!