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

[hukkin]

Hi!
This seems like a dupe of #53 so closing. This feature is very welcome, but behavior should be well defined. I had some concerns: #53 (comment)

Might be good to spec out the corner cases prior to actual implementation.

[pawamoy]

Ah, sorry for missing #53! Will continue discussion there, thanks 🙂