mdformat_admon 2.0.0rc1

An mdformat plugin for admonitions.

mdformat-admon

An mdformat plugin for admonitions, a set of helpers for supporting new admonition syntaxes, and tool for rendering admonition HTML.

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-admon

pipx

pipx install mdformat
pipx inject mdformat mdformat-admon

HTML Rendering

To generate HTML output, any of the internal plugins can be imported as needed.

from markdown_it import MarkdownIt
from mdformat_admon.plugins import python_markdown_admon_plugin

md = MarkdownIt("commonmark")
md.use(plugin)

text = '!!! note ""\n    *content*'
md.render(text)
# <div class="admonition note">
# <p><em>content</em></p>
# </div>

Extensibility

Because admonition syntax varies wildly between implementations, this package provides a set of helpers for building new admonition parsers under mdformat_admon.factories.

• Supported by mdformat-admon
  • python-markdown
• Supported by other packages
  • mdformat-mkdocs
    • MKDocs
• Currently Unsupported (or at least not known to be supported)
  • Github
  • MyST
  • Remark-Admonitions
  • pymdown-extensions
  • reStructuredText (Note: this plugin may break these admonitions by removing or modifying indentation)
  • Obsidian Callouts (Note: this plugin may break these admonitions by adding extra characters)

See the example test file: ./tests/pre-commit-test.md

Contributing

See CONTRIBUTING.md