Markdown Callouts

Common errors

• Markdown extension 'callouts' not found

  cause The `markdown-callouts` package, which provides the 'callouts' extension, is either not installed or not accessible in the current Python environment.
  fix Ensure the package is installed: `pip install markdown-callouts`. If using a virtual environment, activate it before running your build or script.

• SyntaxError: invalid syntax (when trying to write `NOTE: This is a note.` directly in Python code)

  cause Attempting to use Markdown callout syntax directly as Python code. Markdown syntax is not valid Python.
  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.

• Callouts are not rendering or appear as plain blockquotes.

  cause Incorrect callout syntax, leading to the extension not recognizing the block, or the extension itself is not enabled.
  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.

Warnings

• gotcha The package provides two distinct callout extensions: `callouts` and `github-callouts`, which implement different syntaxes.
  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:`.
• gotcha Like all Python-Markdown extensions, `markdown-callouts` must be explicitly enabled to function.
  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.
• gotcha Callout syntax has evolved across versions, introducing new features with specific patterns.
  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.

Install

• pip install markdown-callouts Install latest version

Imports

• callouts

  mkdocs.yml: - callouts
  Python: extensions=['callouts']

  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.
• github-callouts

  mkdocs.yml: - github-callouts
  Python: extensions=['github-callouts']

  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.

Quickstart

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.

# mkdocs.yml
site_name: My Docs

markdown_extensions:
  - callouts
  - github-callouts # For GitHub-style alerts, v0.4.0+

# docs/index.md content example:
# NOTE: This is a standard callout.
# 
# > [!WARNING]
# > This is a GitHub-style alert.
# 
# >? TIP: **Click me for more info.**
# >
# > This content is collapsible.