Admonitions Demo¶

This page demonstrates all the admonition types and features available in our documentation system.

Standard Admonition Types¶

Information Types¶

Note

This is a standard note. Use it for general information that supplements the main content.

Abstract

This is an abstract or summary. Perfect for TL;DR sections or key takeaways.

Information

This provides additional information. Use when you want to highlight supplementary details.

Helpful Tip

This is a tip or hint. Great for best practices and recommendations.

Status Types¶

Success

Operation completed successfully! Use this for positive confirmations.

Question

Have a question? This type is perfect for FAQs or highlighting common queries.

Warning

This is a warning. Use it to alert users to potential issues or important considerations.

Failure

Something went wrong. Use this to indicate errors or failed operations.

Danger

Critical warning! Use this for information that could lead to data loss or security issues.

Development Types¶

Known Bug

This indicates a known issue. Document bugs and their workarounds here.

Example

Here's a practical example. Use this to demonstrate concepts with real code or scenarios.

Quote

"The best way to predict the future is to invent it."
— Alan Kay

Collapsible Admonitions¶

Collapsed by Default¶

Click to expand this note

This content is hidden by default. Users can click the title to reveal it.

This is useful for: - Additional details - Advanced configurations - Optional information

System Requirements (click to view)

OS: Windows 10+, macOS 10.15+, Ubuntu 20.04+
Memory: 8GB RAM minimum, 16GB recommended
Storage: 2GB free space
Node.js: v16.0.0 or higher

Expanded by Default¶

Pro Tips (expanded by default)

These tips are visible immediately:

Use ???+ to expand by default
Use ??? to collapse by default
Users can still toggle the state

Important Configuration

Don't forget to configure these settings:

theme:
  features:
    - content.code.copy
    - content.code.annotate

Custom Titles¶

With Emojis¶

📝 Take Note

Custom titles can include emojis for visual appeal.

💡 Pro Tip

Emojis help users quickly identify admonition types.

⚠️ Caution Required

Use emojis that are universally understood.

Without Titles¶

This admonition has no title, just content. Useful for simple callouts.

Inline Admonitions¶

Sidebar Info

This admonition appears on the right side of the content, allowing text to flow around it.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. This paragraph demonstrates how text flows around inline admonitions.

Left-aligned Tip

This appears on the left side.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Nested Content¶

Code in Admonitions¶

Complete Implementation

Here's a full example with code:

def process_data(data: list) -> dict:
    """Process raw data and return summary statistics."""
    if not data:
        raise ValueError("Data cannot be empty")

    return {
        'count': len(data),
        'sum': sum(data),
        'average': sum(data) / len(data),
        'min': min(data),
        'max': max(data)
    }

Usage:

>>> data = [1, 2, 3, 4, 5]
>>> result = process_data(data)
>>> print(result)
{'count': 5, 'sum': 15, 'average': 3.0, 'min': 1, 'max': 5}

Tabs in Admonitions¶

Installation Instructions

Choose your platform:

pipdockergit

pip install mkdocs-material

docker pull squidfunk/mkdocs-material

git clone https://github.com/squidfunk/mkdocs-material.git
cd mkdocs-material
pip install -e .

Nested Admonitions¶

Main Configuration

Configure the main settings first:

theme:
  name: material

Advanced Options

For more control, add these settings:

theme:
  features:
    - navigation.instant
    - navigation.tracking

Performance Impact

Some features may affect page load times.

Complex Examples¶

Multi-step Process¶

Database Migration Process

Follow these steps carefully:

Step 1: Backup Database ✓

pg_dump mydb > backup.sql

Backup completed successfully!

Step 2: Apply Migrations ✓

python manage.py migrate

All migrations applied!

Step 3: Verify Data

Run verification scripts:

python verify_migration.py

Critical

Do not proceed if verification fails!

Step 4: Update Configuration

Update your settings:

DATABASE_VERSION = '2.0'

Decision Trees¶

Which Framework Should You Use?

For Simple Sites

Recommendation: Use MkDocs

Pros

Easy to set up
Minimal configuration
Fast builds

Cons

Limited customization
Fewer themes

For Complex Documentation

Recommendation: Use Sphinx

Pros

Highly extensible
Many plugins
API documentation

Cons

Steeper learning curve
More configuration

Accessibility Features¶

Screen Reader Support

All admonitions include:

Semantic HTML elements
ARIA labels
Keyboard navigation support
High contrast compatibility

Custom Styling Examples¶

Custom Colors

This admonition can be styled with custom CSS:

.md-typeset .admonition.custom-style {
    border-color: #7c4dff;
}

Best Practices Summary¶

Key Takeaways

Choose the right type - Match the admonition type to your content
Use sparingly - Too many admonitions can overwhelm readers
Keep it concise - Admonitions should enhance, not replace main content
Consider mobile - Test collapsible sections on small screens
Ensure accessibility - Use semantic types and clear titles

Try It Yourself!

Copy any of these examples to your own documentation and customize them to fit your needs.