Skip to content

Custom Icons

Extend MkDocs with custom icons and optimize SVGs for better performance and visual consistency.

Overview

Custom icon features include:

  • Custom Icon Sets - Add your own SVG icons
  • Material Icons Override - Replace default icons
  • Icon Animations - Spin, pulse, and bounce effects
  • SVG Optimization - Automatic cleaning and optimization
  • Multiple Formats - Support for various icon sources
  • Dark Mode Support - Icons adapt to theme

Using Custom Icons

Built-in Material Icons

Material for MkDocs includes thousands of icons:

:material-home: Home :material-github: GitHub
:material-docker: Docker :material-language-python: Python

Custom Icons

We've added custom icons in the custom namespace:

:custom-rocket: :custom-rocket: Rocket :custom-sparkles: :custom-sparkles: Sparkles :custom-code-square: :custom-code-square: Code Square :custom-palette: :custom-palette: Palette

Bootstrap Icons

Additional icons from Bootstrap Icons:

:bootstrap-github: :bootstrap-github: GitHub :bootstrap-twitter: :bootstrap-twitter: Twitter

Icon Sizes

Apply size modifiers using CSS classes:

:custom-rocket: Small icon {.md-icon--small} :custom-rocket: Default size :custom-rocket: Large icon {.md-icon--large} :custom-rocket: Extra large {.md-icon--xlarge}

:custom-rocket:{.md-icon--large}

Icon Animations

Add animations to icons:

:custom-sparkles: Spinning {.md-icon--spin} :custom-rocket: Pulsing {.md-icon--pulse} :custom-code-square: Bouncing {.md-icon--bounce}

:custom-sparkles:{.md-icon--spin}
:custom-rocket:{.md-icon--pulse}
:custom-code-square:{.md-icon--bounce}
:custom-rocket: :custom-rocket:
:custom-sparkles: :custom-sparkles:
:custom-code-square: :custom-code-square:
:custom-palette: :custom-palette:
:material-home: :material-home:
:material-folder: :material-folder:
:material-github: :material-github:
:material-docker: :material-docker:

Adding Custom Icons

1. Create Icon Directory

Create the directory structure:

overrides/
└── .icons/
    └── custom/
        ├── icon1.svg
        ├── icon2.svg
        └── icon3.svg

2. Add SVG Files

Create optimized SVG files with proper viewBox:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
  <path d="M12 2L2 7l10 5 10-5-10-5z"/>
</svg>

3. Configure in mkdocs.yml

theme:
  name: material
  custom_dir: overrides

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons

4. Use in Markdown

:custom-icon-name:

SVG Optimization

Best Practices

  1. Remove Metadata: Strip unnecessary attributes
  2. Use viewBox: Ensure scalability
  3. Optimize Paths: Simplify complex paths
  4. Remove Dimensions: Let CSS control size

Before Optimization

<?xml version="1.0" encoding="UTF-8"?>
<svg width="24px" height="24px" version="1.1" xmlns="http://www.w3.org/2000/svg">
  <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
    <path d="M12,2 L2,7 L12,12 L22,7 L12,2 Z" fill="#000000"/>
  </g>
</svg>

After Optimization

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
  <path d="M12 2L2 7l10 5 10-5-10-5z"/>
</svg>

Logo and Favicon

Logo Configuration

Use custom SVG as logo:

theme:
  logo: assets/logo.svg
  # Or use an icon:
  icon:
    logo: custom/rocket

Favicon Setup

theme:
  favicon: assets/favicon.svg

Favicon Preview

16x16 32x32 48x48 favicon.svg at different sizes

Icon Lists

Use icons in lists for better visual hierarchy:

  • :material-check-circle: Easy to implement
  • :material-palette: Customizable colors
  • :material-devices: Responsive design
  • :material-lock: Secure by default
- :material-check-circle: Easy to implement
- :material-palette: Customizable colors
- :material-devices: Responsive design
- :material-lock: Secure by default

Icon with Text

Combine icons with text:

:custom-rocket: Launch your project with custom icons
:custom-sparkles: Add visual flair to your documentation

Overriding Material Icons

1. Find Original Icon

Locate the icon in Material's .icons directory.

2. Create Override

Create the same path in your overrides:

overrides/
└── .icons/
    └── material/
        └── github.svg  # Overrides the default GitHub icon

3. Custom SVG

Add your custom SVG with the same filename.

CSS Customization

Custom Colors

.md-icon.custom-rocket {
  color: #FF6B6B;
}

Size Variations

.md-icon--small {
  width: 0.9rem;
  height: 0.9rem;
}

Animations

@keyframes spin {
  100% { transform: rotate(360deg); }
}

.md-icon--spin {
  animation: spin 2s linear infinite;
}

Accessibility

Alt Text for Icons

Icons are decorative by default. For meaningful icons:

:material-warning: **Warning**{.visually-hidden}

Color Contrast

Ensure sufficient contrast:

.md-icon {
  color: var(--md-primary-fg-color);
}

Performance Tips

1. Optimize SVGs

  • Use SVGO or similar tools
  • Remove unnecessary elements
  • Simplify paths

2. Icon Sprites

For many icons, consider sprites:

<svg class="icon-sprite">
  <symbol id="icon-rocket" viewBox="0 0 24 24">
    <path d="..."/>
  </symbol>
</svg>

<svg class="md-icon">
  <use href="#icon-rocket"/>
</svg>

3. Lazy Loading

Load icon sets on demand:

if (document.querySelector('[class*="bootstrap-"]')) {
  // Load Bootstrap icons
}

Troubleshooting

Icons Not Showing

  1. Check file paths
  2. Verify SVG syntax
  3. Clear browser cache
  4. Check console errors

Wrong Icon Displayed

  1. Check icon name spelling
  2. Verify namespace (custom vs material)
  3. Clear .cache directory

Styling Issues

  1. Check CSS specificity
  2. Verify class names
  3. Test in different themes