mkdocs-github-admonitions-plugin
Convert GitHub admonitions to mkdocs syntax when building docs.
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
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 · maintenance · safety
permissive license (permissive) — Licensed under MIT (permissive), so you can use, modify, and distribute it freely with minimal restrictions.
last release 2025-06-02 (438 days) · last repo commit 2025-06-02 · 28 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 472,596 downloads/mo, #6,475 on PyPI
Alternatives
Verify before relying
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.- 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.
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 on it.
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
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 | permissive license permissive |
| Python support | Supports the current Python release >=3.8 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 1 packagemkdocs |
| Maintenance | Aging 438 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 472,596 / month, #6,475 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 4 - BetaFramework :: MkDocsIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseNatural Language :: EnglishProgramming Language :: Python :: 3Topic :: Documentation |
Evidence: mkdocs_github_admonitions_plugin-0.1.1-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “mkdocs github admonitions”
- mkdocs-github-admonitions-pluginA MkDocs plugin that converts GitHub-flavored admonitions (using `>…
- mkdocs-techdocs-coreBundles Spotify's TechDocs defaults—themes, plugins, and Markdown…
- markdown-calloutsAdds a cleaner block-level syntax to Markdown for creating…
Give your agent the search over MCP, or paste the wish link into any chat.
More Documentation packages
Docutils converts plaintext documentation in reStructuredText format into multiple output formats including HTML, XML, and LaTeX using a modular processing system.
Sphinx generates professional documentation from reStructuredText source files, producing HTML, PDF, EPUB, and other formats with automatic cross-references, code highlighting, and hierarchical navigation.
Griffe extracts the complete structure and signatures of Python programs to generate API documentation or detect breaking changes in your project's public API.
Install it if you need to programmatically inspect Python code structure, generate API docs, or enforce API stability in CI.
A Sphinx extension that outputs documentation in serialized HTML formats (JSON and pickle) alongside standard HTML.
Alabaster is a clean, responsive Sphinx theme for documentation that requires Python 3.10 or newer and Sphinx 6.2 or newer.
A Sphinx extension that generates HTML help files from reStructuredText documentation source.
See also markdown-callouts · mdformat-mkdocs · mkdocs-video · mkdocs-jupyter · mkdocstrings-python-legacy · mdformat-gfm-alerts · mkdocs-include-markdown-plugin · mkdocs-techdocs-core · mkdocstrings · mkdocs-git-revision-date-plugin