Skip to content

Admonitions

Admonitions, also known as call-outs, are specially styled blocks that help draw attention to important information, warnings, tips, and other noteworthy content.

Overview

Admonitions provide:

  • Visual emphasis - Stand out from regular content
  • Semantic meaning - Different types for different purposes
  • Collapsible content - Optional expand/collapse functionality
  • Custom styling - Extensible with custom types
  • Icon support - Visual indicators for each type
  • Inline usage - Can be used within other content

Configuration

Enable admonitions in mkdocs.yml:

markdown_extensions:
  - admonition
  - pymdownx.details      # For collapsible admonitions
  - pymdownx.superfences  # For nested content

Basic Usage

Standard Types

Note

This is a note admonition. Use it for general information.

Abstract

This is an abstract admonition. Use it for summaries.

Info

This is an info admonition. Use it for informational content.

Tip

This is a tip admonition. Use it for helpful hints.

Success

This is a success admonition. Use it for successful outcomes.

Question

This is a question admonition. Use it for FAQs or queries.

Warning

This is a warning admonition. Use it for important cautions.

Failure

This is a failure admonition. Use it for failed operations.

Danger

This is a danger admonition. Use it for critical warnings.

Bug

This is a bug admonition. Use it for known issues.

Example

This is an example admonition. Use it for code examples.

Quote

This is a quote admonition. Use it for quotations.

Syntax

!!! note
    This is a note with default title.

!!! note "Custom Title"
    This is a note with a custom title.

!!! note ""
    This is a note with no title.

Collapsible Admonitions

Collapsed by Default

Click to expand

This content is hidden by default.

Users can click to reveal it.

Expanded by Default

Expanded by default

This content is visible by default.

Users can click to collapse it.

Syntax

??? note "Collapsed admonition"
    Hidden content

???+ tip "Expanded admonition"
    Visible content

Custom Titles and Types

Custom Titles

Did you know?

You can customize the title of any admonition.

⚠️ Important Notice

Titles can include emojis and special characters.

Custom Types

Settings

Create custom admonition types with CSS.

/* Custom admonition styling */
.md-typeset .admonition.settings,
.md-typeset details.settings {
  border-color: #448aff;
}

.md-typeset .settings > .admonition-title,
.md-typeset .settings > summary {
  background-color: #448aff1a;
}

.md-typeset .settings > .admonition-title::before,
.md-typeset .settings > summary::before {
  background-color: #448aff;
  content: "⚙️";
}

Nested Content

Complex Content

Complete Example

Here's a full implementation:

def calculate_discount(price, discount_percent):
    """Calculate the discounted price."""
    discount = price * (discount_percent / 100)
    return price - discount

Usage:

final_price = calculate_discount(100, 20)
print(f"Final price: ${final_price}")

Final price: $80.0

Tip

Remember to validate inputs!

Nested Admonitions

Main Topic

This is the main content.

Additional Details

Here are more details if you're interested.

Important

Don't forget this crucial point!

Inline Admonitions

Use admonitions inline with other content:

Tip

This tip appears alongside the main text, floating to the right.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.

Info

This appears inline on the left.

More content continues here after the inline admonition.

Styling and Customization

Color Schemes

Each admonition type has a distinct color:

Type Color Use Case
note Blue General information
abstract Light blue Summaries
info Cyan Information
tip Green Helpful hints
success Green Success messages
question Light green Questions
warning Orange Warnings
failure Red Failures
danger Red Critical warnings
bug Pink Bug reports
example Purple Examples
quote Grey Quotations

Custom CSS

/* docs/assets/stylesheets/admonitions.css */

/* Custom admonition colors */
.md-typeset .admonition.custom {
  border-color: #7c4dff;
}

.md-typeset .custom > .admonition-title {
  background-color: #7c4dff1a;
  border-color: #7c4dff;
}

.md-typeset .custom > .admonition-title::before {
  background-color: #7c4dff;
  content: "✨";
}

/* Modify existing types */
.md-typeset .admonition.note {
  font-size: 0.9rem;
}

/* Animations */
.md-typeset details[open] > summary ~ * {
  animation: fadeIn 0.3s ease-in-out;
}

@keyframes fadeIn {
  from { opacity: 0; transform: translateY(-10px); }
  to { opacity: 1; transform: translateY(0); }
}

Best Practices

1. Appropriate Usage

Use the right type for the content:

✅ Good:
!!! warning "Deprecation Notice"
    This feature will be removed in v3.0

❌ Bad:
!!! tip "Deprecation Notice"
    This feature will be removed in v3.0

2. Clear Titles

Provide descriptive titles:

✅ Good:
!!! info "Database Connection Requirements"
    PostgreSQL 12+ is required

❌ Bad:
!!! info "Note"
    PostgreSQL 12+ is required

3. Concise Content

Keep admonitions focused:

✅ Good:
!!! tip "Performance Tip"
    Use indexes on frequently queried columns.

❌ Bad:
!!! tip "Performance"
    Here's everything about database performance...
    [500 lines of content]

4. Sparing Use

Don't overuse admonitions:

  • Use for truly important information
  • Limit to 2-3 per page section
  • Avoid consecutive admonitions

Common Patterns

Prerequisites

Prerequisites

Before starting, ensure you have:

  • Python 3.8 or higher
  • pip package manager
  • Virtual environment (recommended)

Warnings

Security Warning

Never commit sensitive data like API keys or passwords to version control.

Version Notes

Version Compatibility

This feature is available in version 2.0 and above.

Deprecation Notices

Deprecated

This method is deprecated and will be removed in version 3.0.

Use new_method() instead: 

# Old way (deprecated)
old_method()

# New way
new_method()

Tips and Tricks

Pro Tip

Hold Shift while clicking to open links in a new window.

Troubleshooting

Common Issues

Problem: Feature not working

Solution: Check these common causes:

  1. Verify configuration is correct
  2. Clear browser cache
  3. Check for JavaScript errors
  4. Ensure all dependencies are installed

Advanced Usage

Dynamic Admonitions

Using JavaScript to create interactive admonitions:

// Create dynamic alerts
function showAlert(type, title, message) {
  const alert = document.createElement('div');
  alert.className = `admonition ${type}`;
  alert.innerHTML = `
    <p class="admonition-title">${title}</p>
    <p>${message}</p>
  `;
  document.getElementById('alerts').appendChild(alert);
}

Admonitions in Tables

Feature Status Notes
Feature A ✅ !!! success inline end "Stable"
Production ready
Feature B ⚠️ !!! warning inline end "Beta"
Use with caution
Feature C ❌ !!! danger inline end "Alpha"
Not recommended		 
/* Optimize admonitions for printing */
@media print {
  .md-typeset .admonition {
    break-inside: avoid;
    border: 2px solid #000;
  }

  .md-typeset details {
    open: true !important;
  }
}

Accessibility

Admonitions include:

  • Semantic HTML structure
  • ARIA labels for screen readers
  • Keyboard navigation for collapsible sections
  • High contrast mode support
  • Clear visual indicators

Screen Reader Support

<!-- Generated HTML structure -->
<div class="admonition note" role="note">
  <p class="admonition-title">Note</p>
  <p>Content is announced properly to screen readers</p>
</div>

Integration

With Code Blocks

API Request Example

import requests

response = requests.get('https://api.example.com/data')
data = response.json()

Warning

Always handle exceptions when making HTTP requests!

With Tabs

Platform-Specific Instructions

Use the Windows installer from our downloads page.

Install via Homebrew: 

brew install ourapp

Use your distribution's package manager.

See Also