README.md

mdformat-gfm-alerts

An mdformat plugin for GitHub "Alerts". "Alerts" are a block quote variation of admonitions that were proposed in this community discussion and are currently a separate extension of the GFM (GitHub-Flavored Markdown) syntax.

mdformat Usage

Add this package wherever you use mdformat and the plugin will be auto-recognized. No additional configuration necessary. See additional information on mdformat plugins here

Pre-Commit

repos:
  - repo: https://github.com/executablebooks/mdformat
    rev: 0.7.16
    hooks:
      - id: mdformat
        additional_dependencies:
          - mdformat-gfm-alerts

pipx

pipx install mdformat
pipx inject mdformat mdformat-gfm-alerts

HTML Rendering

To generate HTML output, gfm_alerts_plugin can be imported from mdit_plugins. For more guidance on MarkdownIt, see the docs: https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser

from markdown_it import MarkdownIt

from mdformat_gfm_alerts.mdit_plugins import gfm_alerts_plugin

md = MarkdownIt()
md.use(gfm_alerts_plugin)

text = "> [!NOTE]\n> Useful information that users should know, even when skimming content. "
md.render(text)
# <blockquote>
# <div class="markdown-alert markdown-alert-note">
# <p class="markdown-alert-title">Note</p>
# <p>Useful information that users should know, even when skimming content.</p>
# </div>
# </blockquote>

Warning

This package does not properly handle replacing the blockquote outer div with a div for accessibility. This should be possible with markdown-it, but I haven't yet found a way.

Contributing

See CONTRIBUTING.md