search

facelessuser / pymdown-extensions

Extensions for Python Markdown
https://facelessuser.github.io/pymdown-extensions/
Other
949 stars 253 forks source link

mdformat currently breaks usage of the snippets plugin because it escapes "<" characters. It would be very useful to have a mdformat plugin for snippets support. #2434

Closed mmcdermott closed 5 days ago

mmcdermott commented 1 month ago

Description

mdformat is a common markdown linter. It supports plugins that can customize its behavior to support non-standard markdown syntax (e.g., for admonition)

This issue in mdformat illustrates that it currently by default escapes the "<" character and there is no way around this. It would be nice if there were an mdformat plugin for snippets so that it could be properly linted when using mdformat.

Benefits

Users would be able to use mdformat with snippets.

Solution Idea

There is a template for making new mdformat plugins here: https://github.com/executablebooks/mdformat-plugin

facelessuser commented 1 month ago

Snippets is meant to be run before Markdown parsing as it is a preprocessor extension within Python Markdown. Unfortunately, mdformat is not aware of such things. mdformat also uses a different Markdown parser, so it cannot run Snippets. I am unfamiliar with the mdformat tool, but it seems to be built on markdown-it, not Python Markdown.

From reading the linked issue, Snippets is not the only affected extension, and they are yet to provide a formal response as well. I would like them to provide a formal statement. There should probably be a general mitigation approach explained there since there are various plugins affected by this. There appears to be no comment from an official developer in the year it was filed.

Someone familiar with markdown-it and mdformat would probably be better at providing a solution than I as I have absolutely no experience with these tools. Since I don't currently use mdformat, the motivation is kind of low on my end to learn it at this time.

Aside from changing the format of Snippets, I'm not sure there is anything I can do at this time. I currently don't have plans for rewriting the syntax for Snippets.

For now, I will leave this open. Maybe others in the community with an interest here can provide more information or would like to contribute a solution.

mmcdermott commented 1 month ago

That all sounds totally reasonable @facelessuser -- thanks for the quick response! I've commented on the issue on their side as well so hopefully they can provide a mitigation as well.