mkdocs-github-admonitions-plugin

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 on this page — 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

mkdocs-github-admonitions-plugin on PyPI

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

Evidence: mkdocs_github_admonitions_plugin-0.1.1-py3-none-any.whl

Keywords: admonition, github, material, mkdocs

Tags

More Documentation packages