markdown-callouts is a Python-Markdown extension that enhances documentation with admonition-style callouts. It supports various syntaxes, including a flexible original style (e.g., `NOTE:`), collapsible blocks (`>? TIP:`), and the GitHub 'alerts' syntax (`> [!NOTE]`). The current version is 0.4.0, and new features are added incrementally, often focusing on compatibility with existing Markdown parsers and popular documentation tools like MkDocs.
pip install markdown-calloutsVerified import paths — ran on the pinned version, not inferred.
To use markdown-callouts, enable the desired extensions in your `mkdocs.yml` file (for MkDocs projects) or pass them to the `extensions` parameter when initializing the `markdown.Markdown` parser in Python. The example demonstrates common usage within an MkDocs project.
Enable both `callouts` and `github-callouts` in your `markdown_extensions` list (or `extensions` parameter) if you intend to use both the original flexible syntax and the GitHub-style `> [!TYPE]` alerts. The `github-callouts` extension handles the GitHub syntax, while `callouts` handles `NOTE:` and `>? TIP:`.
Always add `callouts` and/or `github-callouts` to the `markdown_extensions` list in your `mkdocs.yml` or pass them in the `extensions` parameter when using `markdown.markdown()` in Python code. The extensions are not active by default.
Refer to the official documentation for the exact syntax for specific features: custom titles (v0.2.0+), collapsible blocks (v0.3.0+), and GitHub alerts (v0.4.0+). Incorrect or legacy syntax may not render as expected or might be ignored.