MkDocs Material Extensions

1.3.1 · deprecated · verified Sun Apr 05

This library, `mkdocs-material-extensions`, provides an extension pack for Python Markdown specifically designed to work with the MkDocs Material theme. As of version 1.3 (released November 2023), this project is deprecated and considered obsolete because its core logic has been integrated directly into `mkdocs-material` (version 9.4 and above). Users are strongly advised to migrate to the equivalent functionalities provided by `mkdocs-material` itself. It primarily facilitated inline SVG icons and emoji handling within MkDocs Material documentation.

Warnings

breaking This library is deprecated and obsolete since `mkdocs-material` version 9.4, which now includes this library's functionality directly. Users *must* migrate their `mkdocs.yml` configuration from `materialx.emoji.twemoji` and `materialx.emoji.to_svg` to `material.extensions.emoji.twemoji` and `material.extensions.emoji.to_svg` respectively. Continuing to use this library with `mkdocs-material` versions 9.4+ may lead to unexpected behavior or build issues.
Fix: Remove `mkdocs-material-extensions` from your project dependencies (`pip uninstall mkdocs-material-extensions`). Update your `mkdocs.yml` to use `material.extensions.emoji.twemoji` and `material.extensions.emoji.to_svg` instead of `materialx.emoji.*` references.
deprecated Support for Python 3.6 was dropped in version 1.1, and Python 3.7 support was removed in version 1.2. Users on these older Python environments will need to upgrade to Python 3.8 or higher to use newer versions of `mkdocs-material-extensions` or the integrated functionality in `mkdocs-material`.
Fix: Upgrade your Python environment to 3.8 or higher.
gotcha Version 1.0.2 addressed a circular dependency issue where `mkdocs-material-extensions` listed `mkdocs-material` as a dependency, while `mkdocs-material` also depended on `mkdocs-material-extensions`. While `pip` handled this, some other versioning tools experienced issues. `mkdocs-material` now manages the necessary version of this library directly, so explicit installation of `mkdocs-material-extensions` is usually not required unless troubleshooting or working with very specific, older setups.
Fix: Ensure `mkdocs-material` is installed; typically, `mkdocs-material-extensions` will be pulled in as a transitive dependency if needed. Avoid explicit dependency on `mkdocs-material-extensions` unless absolutely necessary for specific version pinning scenarios, especially with older `mkdocs-material` versions.

Install

pip install mkdocs-material-extensions Pip Install

Imports

twemoji (for YAML config)
```
!!python/name:materialx.emoji.twemoji
```
This was the YAML reference for the custom emoji index in `mkdocs.yml`. It is now superseded by `!!python/name:material.extensions.emoji.twemoji` within `mkdocs-material` versions 9.4 and later.
to_svg (for YAML config)
```
!!python/name:materialx.emoji.to_svg
```
This was the YAML reference for the custom emoji generator in `mkdocs.yml`. It is now superseded by `!!python/name:material.extensions.emoji.to_svg` within `mkdocs-material` versions 9.4 and later.

Quickstart

This quickstart demonstrates the *deprecated* configuration of `mkdocs-material-extensions` in your `mkdocs.yml` file, primarily for enabling inline SVG icons and emoji. The library is now obsolete, and its functionality is integrated directly into `mkdocs-material`. The commented section shows the required changes to migrate your configuration to `mkdocs-material` versions 9.4 and above.

# mkdocs.yml (Deprecated configuration for mkdocs-material-extensions)
markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg

# --- MIGRATION PATH for MkDocs Material v9.4+ (mkdocs.yml) ---
# Remove `mkdocs-material-extensions` from your project dependencies.
# Update your mkdocs.yml to use the native extensions provided by mkdocs-material:
# markdown_extensions:
#   - pymdownx.emoji:
#       emoji_index: !!python/name:material.extensions.emoji.twemoji
#       emoji_generator: !!python/name:material.extensions.emoji.to_svg

view raw JSON →