Support Admonitions

[KyleKing]

Describe the problem/need and solution

Problem

Right now, mdformat breaks indentation for admonitions. Below is a repeatable example based on the first snippet from the admonition documentation

~/Developer > pipx install mdformat-gfm --include-deps
  installed package mdformat-gfm 0.3.5, installed using Python 3.10.2
  These apps are now globally available
    - markdown-it
    - mdformat
done! ✨ 🌟 ✨
~/Developer > pbpaste > ad_test.md
~/Developer > bat ad_test.md
───────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
       │ File: ad_test.md
───────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   1   │ !!! type "optional explicit title within double quotes"
   2   │     Any number of other indented markdown elements.
   3   │
   4   │     This is the second paragraph.
───────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
~/Developer > mdformat ad_test.md
~/Developer > bat ad_test.md
───────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
       │ File: ad_test.md
───────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   1   │ !!! type "optional explicit title within double quotes"
   2   │ Any number of other indented markdown elements.
   3   │
   4   │ ```
   5   │ This is the second paragraph.
   6   │ ```
───────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Solution

admonitions are not part of the CommonMark specification and would be best handled by a plugin (i.e. mdformat-admonition)

I would be happy to try writing one, but I wanted to open an issue first so that I'm not duplicating effort. I saw that there was at least one other issue with admonition problems, but there didn't seem to be any updates since: #53 (https://github.com/executablebooks/mdformat/issues/53#issuecomment-928306196)

• I naively think the plugin shouldn't be too difficult to implement
  • I found the plugin template: https://github.com/executablebooks/mdformat-plugin
    • and the mdformat-tables, mdformat-frontmatter, mdformat-footnote, and mdformat source will be useful to reference
  • Update: As a reference, here is a plugin that was recently ported with a good implementation

Benefit

Would be nice to have support for admonitions (particular for mkdocs which uses the markdown extension)

Guide for implementation

No response

Tasks and updates

No response

[hukkin]

Hey thanks for the issue!

Yeah this should be a plugin, and the plugin template you linked should be helpful. The first step, however, is a parser extension for mdformat's Markdown parser (markdown-it-py which is a Python port of the JavaScript markdown-it).

You'll find the existing parser extensions in this collection repository: https://github.com/executablebooks/mdit-py-plugins. I suggest making a PR there (although it's entirely possible that you keep in a separate repo too).

Luckily you don't have to start from scratch: there seems to be a JavaScript version of the parser extension which you can port to Python https://github.com/commenthol/markdown-it-admon (I dont know whether the JS implementation is any good though).

[KyleKing]

Great! I've got a busy next few weeks, but I'll start on this once I have time!

[lorenzomorandini]

@KyleKing had any chance to work on this?

[KyleKing]

Thanks for reminder. I had completed forgotten about this ticket. This is still an issue for me, but haven't had time to work on it

[lyz-code]

@KyleKing I guess there is still no advance, isn't it?

[KyleKing]

Yeah, no progress yet

I actually had these tickets open to try to get to it this week, but haven't had time yet with school and holidays here

[KyleKing]

Submitted a PR! It is a Draft, but I'll finish up and mark it ready for review sometime tomorrow

[KyleKing]

And I started the plugin for mdformat-admon here: https://github.com/KyleKing/mdformat-admon

[KyleKing]

This ticket keeps accidentally closing...but I had some time to make progress today!

If anyone is more familiar with mdformat and can weigh in on my implementation, let me know:

https://github.com/KyleKing/mdformat-admon/blob/main/mdformat_admon/plugin.py

[KyleKing]

After a long, busy year, I finally have a v0.0.1 release of the admonition plugin!

I will test it in a real world project and will revisit if formats other than !!! will be supported, but I think we can close this issue (third times the charm!) and track any issues around admonition support in: https://github.com/KyleKing/mdformat-admon/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc 🎉