Admonition Configuration

This guide covers advanced configuration options for admonitions in MkDocs with Material theme.

Basic Configuration

Required Extensions

Add these to your mkdocs.yml:

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

Theme Configuration

Material Theme Features

Enable enhanced admonition features:

theme:
  name: material
  features:
    - content.tooltips    # For tooltip support
  palette:
    - scheme: default
      primary: indigo
      accent: indigo

Custom Admonition Types

Creating Custom Types

1. Define the CSS:

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

.md-typeset .admonition.custom-type,
.md-typeset details.custom-type {
  border-color: #7c4dff;
}

.md-typeset .custom-type > .admonition-title,
.md-typeset .custom-type > summary {
  background-color: rgba(124, 77, 255, 0.1);
}

.md-typeset .custom-type > .admonition-title::before,
.md-typeset .custom-type > summary::before {
  background-color: #7c4dff;
  -webkit-mask-image: var(--md-admonition-icon--custom-type);
  mask-image: var(--md-admonition-icon--custom-type);
  content: "";
}

1. Define the Icon:

:root {
  --md-admonition-icon--custom-type: url('data:image/svg+xml;charset=utf-8,<svg>...</svg>');
}

1. Use in Markdown:

!!! custom-type "Custom Title"
    Your content here

Example Custom Types

Prerequisites Type

.md-typeset .admonition.prerequisites,
.md-typeset details.prerequisites {
  border-color: #9c27b0;
}

.md-typeset .prerequisites > .admonition-title::before,
.md-typeset .prerequisites > summary::before {
  content: "📋";
}

Usage:

Before You Begin

• Python 3.8+
• Node.js 16+
• Git

API Type

.md-typeset .admonition.api,
.md-typeset details.api {
  border-color: #ff6f00;
}

.md-typeset .api > .admonition-title::before,
.md-typeset .api > summary::before {
  content: "🔌";
}

Icon Configuration

Using Material Icons

theme:
  icon:
    admonition:
      note: material/notebook
      abstract: material/file-document
      info: material/information
      tip: material/lightbulb
      success: material/check-circle
      question: material/help-circle
      warning: material/alert
      failure: material/close-circle
      danger: material/alert-circle
      bug: material/bug
      example: material/test-tube
      quote: material/format-quote

Custom Icon Sets

1. Add custom icons:

theme:
  custom_dir: overrides

1. Create icon files:

overrides/
  .icons/
    custom/
      my-icon.svg

1. Reference in admonitions:

theme:
  icon:
    admonition:
      custom: custom/my-icon

Styling Options

Color Schemes

Light Theme Colors

[data-md-color-scheme="default"] {
  --md-admonition-fg-color: rgba(0, 0, 0, 0.87);
  --md-admonition-bg-color: var(--md-default-bg-color);
}

Dark Theme Colors

[data-md-color-scheme="slate"] {
  --md-admonition-fg-color: rgba(255, 255, 255, 0.87);
  --md-admonition-bg-color: var(--md-default-bg-color);
}

Typography

.md-typeset .admonition {
  font-size: 0.84rem;
}

.md-typeset .admonition-title {
  font-weight: 700;
  font-size: 0.84rem;
}

Advanced Features

Automatic Admonitions

Use snippets to create reusable admonitions:

1. Create snippet file:

<!-- includes/warnings/deprecated.md -->
!!! danger "Deprecated Feature"
    This feature is deprecated and will be removed in the next major version.

1. Use in documentation:

Dynamic Admonitions

Create interactive admonitions with JavaScript:

// docs/assets/javascripts/admonitions.js

document.addEventListener('DOMContentLoaded', function() {
  // Add click tracking to admonitions
  document.querySelectorAll('.admonition').forEach(function(adm) {
    adm.addEventListener('click', function() {
      console.log('Admonition clicked:', adm.className);
    });
  });

  // Auto-expand important admonitions
  document.querySelectorAll('details.important').forEach(function(details) {
    details.setAttribute('open', '');
  });
});

Contextual Admonitions

Show different admonitions based on context:

// Show version-specific warnings
if (window.location.pathname.includes('/v1/')) {
  document.querySelectorAll('.version-warning').forEach(function(el) {
    el.style.display = 'block';
  });
}

Integration with Other Features

With Code Annotations

!!! example "Annotated Code"

    ```python
    def process(data):
        result = []
        for item in data:  # (1)!
            if validate(item):  # (2)!
                result.append(transform(item))
        return result
    ```

    1. Iterate through each data item
    2. Validate before processing

With Content Tabs

!!! tip "Platform-Specific Tips"

    === "Windows"
        Use PowerShell for better Unicode support

    === "Linux/macOS"  
        Use the terminal's built-in features

With Keyboard Keys

!!! tip "Keyboard Shortcut"
    Press ++ctrl+shift+p++ to open the command palette

Performance Optimization

Lazy Loading

/* Defer icon loading */
.md-typeset .admonition-title::before {
  content: "";
  loading: lazy;
}

Reduce Animations

/* Prefers reduced motion */
@media (prefers-reduced-motion: reduce) {
  .md-typeset details[open] > summary ~ * {
    animation: none;
  }
}

Accessibility Configuration

ARIA Labels

// Add ARIA labels dynamically
document.querySelectorAll('.admonition').forEach(function(adm) {
  const type = adm.className.match(/admonition (\w+)/)[1];
  adm.setAttribute('role', 'note');
  adm.setAttribute('aria-label', `${type} admonition`);
});

Keyboard Navigation

/* Enhanced focus styles */
.md-typeset details > summary:focus-visible {
  outline: 3px solid var(--md-accent-fg-color);
  outline-offset: 2px;
  border-radius: 2px;
}

Troubleshooting

Common Issues

1. Icons not showing: Check SVG syntax and encoding
2. Colors not applying: Verify CSS specificity
3. Animations stuttering: Reduce complexity or disable
4. Mobile layout issues: Test responsive CSS

Debug Mode

/* Visual debugging */
.debug .admonition {
  border: 2px dashed red !important;
}

.debug .admonition-title::after {
  content: " [" attr(class) "]";
  font-size: 0.7em;
  opacity: 0.5;
}

Best Practices

1. Consistent Usage: Use the same admonition types for similar content
2. Clear Titles: Make titles descriptive and action-oriented
3. Appropriate Icons: Choose icons that match the content meaning
4. Test Accessibility: Verify with screen readers and keyboard navigation
5. Mobile First: Design for mobile and enhance for desktop

See Also

• Admonitions Feature Guide
• PyMdown Extensions
• Theme Configuration