---
id: mdformat-gfm-alerts
version: "2.1.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# mdformat-gfm-alerts — Format 'GitHub Markdown Alerts,' which use blockquotes to render admonitions

License: permissive · Maintenance: active · Downloads: 169.4K/mo

## What it is and what it does

mdformat-gfm-alerts is a plugin that extends mdformat to recognize and format GitHub Flavored Markdown (GFM) Alerts—a GitHub-native syntax for rendering admonitions using blockquotes with alert markers like `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]`. It ensures these alerts conform to GitHub's specification by normalizing their structure during markdown formatting.

The plugin works by integrating directly into mdformat's pipeline; once installed, it is automatically recognized and requires no additional configuration. By default, it follows strict GitHub behavior (folding custom titles into the alert body), but a `--custom-title` option allows preserving inline titles on the marker line for compatibility with other conventions like Hugo's alert syntax.

Use it for:

- Standardize GitHub alert syntax across a documentation repository to match GitHub's rendering behavior
- Auto-format markdown files in CI/CD pipelines using mdformat with consistent alert structure
- Convert or normalize alert blocks when migrating markdown between GitHub and other platforms
- Enforce alert formatting rules in pre-commit hooks alongside other markdown linting
- Integrate alert formatting into mdformat workflows without manual configuration

## Worth the install?

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

A plugin for mdformat that formats GitHub Markdown Alerts (blockquote-based admonitions using `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]` syntax) according to GitHub's specification.

Yes, if you use mdformat and work with GitHub Markdown Alerts in your documentation. The plugin has low install friction, active maintenance, permissive licensing, no known vulnerabilities, and integrates seamlessly into mdformat's workflow. Install it if you need consistent alert formatting; skip it if you don't use GFM alerts.

## Install

pip install mdformat-gfm-alerts
uv add mdformat-gfm-alerts
poetry add mdformat-gfm-alerts

## Installing mdformat-gfm-alerts

Before you install: Low install friction; pure Python wheel with only two runtime dependencies (mdformat and mdit-py-plugins). Active maintenance with a recent release 19 days ago.

License in practice: MIT license (permissive); you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart:

# Install alongside mdformat
pip install mdformat mdformat-gfm-alerts

# Format markdown files (plugin auto-recognized)
mdformat file.md

# Or import the plugin:
from mdformat_gfm_alerts.mdit_plugins import gfm_alerts_plugin

Requires Python >=3.10.0

Verify before relying:

- Whether the plugin handles edge cases beyond the five canonical GitHub alert types
- Performance characteristics when formatting large markdown files with many alerts
- Full scope of HTML rendering capabilities and output format details

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 169.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

github markdown alerts formatting, mdformat gfm alerts plugin, blockquote admonitions markdown, github alerts syntax formatter, markdown alert standardization, gfm alerts mdformat, github callout formatting, markdown-formatting, github-alerts, mdformat-plugin

[View on SkillFed](https://skillfed.io/packages/mdformat-gfm-alerts) · [View on PyPI](https://pypi.org/project/mdformat-gfm-alerts/)