On/off comments

[pawamoy]

Context

I'm evaluating mdformat in one of my projects (actually my MkDocs-based website).

It's super useful already, but obviously there are some incompatibilities between the parser used by mdformat and the one used by MkDocs (Python-Markdown). I don't mind these incompatibilities, and would actually like to write plugins myself to support Python-Markdown extensions 🙂 (if it's at all possible 🤔?)

In the meantime, it would be great if I could add on/off comments to my Markdown document to prevent mdformat from formatting some snippets. Typically, mkdocstrings instructions that look like this:

::: path.to.object
    options:
      show_source: false

...and get reformatted like this:

::: path.to.object options: show_source: false

Proposal

I would suggest supporting on/off comments like the following:

<!-- mdformat: off -->

::: path.to.object
    options:
      show_source: false

<!-- mdformat: on -->

I have implemented the same thing for blacken-docs (though still waiting review), so could probably send a PR to mdformat too, if this feature is something you'd like to have 🙂

Tasks and updates

No response