---
id: mkdocs-github-admonitions-plugin
version: "0.1.1"
license: unclear
license_treatment: permissive
maintenance: aging
---

# mkdocs-github-admonitions-plugin — Convert GitHub admonitions to mkdocs syntax when building docs.

License: permissive · Maintenance: aging · Downloads: 472.6K/mo

## What it is and what it does

This is a MkDocs plugin that solves a markdown compatibility problem: GitHub and MkDocs each support admonitions, but with incompatible syntax. GitHub uses `> [!TYPE]` blocks while MkDocs uses `!!! type` blocks. The plugin intercepts your markdown during the build process and converts GitHub-style admonitions to MkDocs syntax, so you can write admonitions once in GitHub's format and have them render correctly in both places.

The plugin supports GitHub's admonition types (note, tip, important, warning, caution) and also GitLab alerts. It handles edge cases like mixed case types and preserves content including inline code and nested lists. Two GitHub types (caution, important) map to MkDocs equivalents (danger, warning) with the original title preserved. The plugin is lightweight, depending only on mkdocs itself, and requires Python 3.8 or later.

Use it for:

- Write documentation in a single markdown source that displays admonitions correctly on GitHub and in your built MkDocs site without duplication.
- Migrate existing GitHub README admonitions into MkDocs documentation while keeping the same markdown syntax.
- Maintain consistent admonition styling across GitHub-hosted projects and their generated documentation sites.
- Use GitLab alerts in markdown and have them automatically converted for MkDocs builds.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A MkDocs plugin that converts GitHub-flavored admonitions (using `> [!TYPE]` syntax) to MkDocs-compatible admonitions so the same markdown renders correctly in both GitHub and built documentation.

Yes, if you maintain documentation in both GitHub and MkDocs. The plugin solves a real friction point—write-once admonitions that work everywhere—with low install friction and no security concerns. The aging maintenance status (438 days since last release) is not a blocker for a stable, focused tool, but verify it still works with your MkDocs version before relying on it for a new project.

## Install

pip install mkdocs-github-admonitions-plugin
uv add mkdocs-github-admonitions-plugin
poetry add mkdocs-github-admonitions-plugin

## Installing mkdocs-github-admonitions-plugin

Before you install: Low friction: pure Python wheel with a single runtime dependency on mkdocs. Maintenance status is aging—last release was 438 days ago—but the repository remains active and unarchived, suggesting the plugin is stable rather than abandoned.

License in practice: Licensed under MIT (permissive), so you can use, modify, and distribute it freely with minimal restrictions.

Quickstart:

pip install mkdocs-github-admonitions-plugin

Then add to mkdocs.yml:
plugins:
  - gh-admonitions

Now write GitHub admonitions in your markdown:
> [!TIP]
> This will render on GitHub and in built MkDocs pages.

Verify before relying:

- Whether GitLab alerts support is fully tested and documented (mentioned as added but not detailed in the excerpt).
- Whether the plugin works with all MkDocs Material theme versions or has specific version constraints.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 472.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs github admonitions, convert github admonitions mkdocs, admonition syntax converter, mkdocs plugin github compatibility, markdown admonition bridge, github to mkdocs markdown, admonition markdown plugin, markdown-conversion, github-compat

[View on SkillFed](https://skillfed.io/packages/mkdocs-github-admonitions-plugin) · [View on PyPI](https://pypi.org/project/mkdocs-github-admonitions-plugin/)