{"id":9916,"library":"markdown-callouts","title":"Markdown Callouts","description":"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.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/oprypin/markdown-callouts","tags":["markdown","mkdocs","admonitions","documentation","extension","alerts"],"install":[{"cmd":"pip install markdown-callouts","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for Python-Markdown extensions; `markdown-callouts` extends `Markdown.extensions.Extension`.","package":"Markdown","optional":false}],"imports":[{"note":"This is a string identifier for the Markdown extension, used in configuration files (MkDocs) or when initializing the Markdown parser (Python). It is not a Python module to be imported directly.","symbol":"callouts","correct":"mkdocs.yml: - callouts\nPython: extensions=['callouts']"},{"note":"Introduced in v0.4.0, this string identifier enables the GitHub-style 'alerts' syntax (`> [!NOTE]`). It can be used alongside the 'callouts' extension if both syntaxes are desired. Not a direct Python import.","symbol":"github-callouts","correct":"mkdocs.yml: - github-callouts\nPython: extensions=['github-callouts']"}],"quickstart":{"code":"# mkdocs.yml\nsite_name: My Docs\n\nmarkdown_extensions:\n  - callouts\n  - github-callouts # For GitHub-style alerts, v0.4.0+\n\n# docs/index.md content example:\n# NOTE: This is a standard callout.\n# \n# > [!WARNING]\n# > This is a GitHub-style alert.\n# \n# >? TIP: **Click me for more info.**\n# >\n# > This content is collapsible.","lang":"yaml","description":"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."},"warnings":[{"fix":"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:`.","message":"The package provides two distinct callout extensions: `callouts` and `github-callouts`, which implement different syntaxes.","severity":"gotcha","affected_versions":"v0.4.0+"},{"fix":"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.","message":"Like all Python-Markdown extensions, `markdown-callouts` must be explicitly enabled to function.","severity":"gotcha","affected_versions":"All versions"},{"fix":"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.","message":"Callout syntax has evolved across versions, introducing new features with specific patterns.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed: `pip install markdown-callouts`. If using a virtual environment, activate it before running your build or script.","cause":"The `markdown-callouts` package, which provides the 'callouts' extension, is either not installed or not accessible in the current Python environment.","error":"Markdown extension 'callouts' not found"},{"fix":"The callout syntax is for Markdown files (`.md`). Write your callouts in your Markdown content, then process those files using a Markdown parser (e.g., `markdown.markdown(text, extensions=['callouts'])`) or a documentation generator like MkDocs.","cause":"Attempting to use Markdown callout syntax directly as Python code. Markdown syntax is not valid Python.","error":"SyntaxError: invalid syntax (when trying to write `NOTE: This is a note.` directly in Python code)"},{"fix":"1. Verify the exact callout syntax (e.g., `NOTE: ` requires a space after the colon, `> [!WARNING]` needs the exact `> [!TYPE]` pattern, including the space after `>`). 2. Ensure the correct extension (`callouts` or `github-callouts`) is properly enabled in your configuration.","cause":"Incorrect callout syntax, leading to the extension not recognizing the block, or the extension itself is not enabled.","error":"Callouts are not rendering or appear as plain blockquotes."}]}