mdformat plugins

[bquorning]

I am a little confused about how to enable/disable installed plugins when using the mdformat CLI. The documentation states that both code formatter plugins and parser extension plugins have to be explicitly enabled, not just installed:

For stability, mdformat Python API behavior will not change simply due to a plugin being installed.
Code formatters will have to be explicitly enabled in addition to being installed:¹

and

For stability, mdformat Python API behavior will not change simply due to a plugin being installed.
Extensions will have to be explicitly enabled in addition to being installed:²

However, it seems that the mdformat CLI will enable any plugins that is installed, and I can find no way to not enable any of the installed plugins. For example:

I have a small file with some GitHub formatted Markdown:

❯ cat doc.md                                   
TODO

- [ ] foo
- [ ] bar[^1]

[^1]: This is a footnote

I have no mdformat plugins installed:

❯ mdformat --version                                                                                        
mdformat 0.7.14

and mdformat doesn't like the GFM syntax

❯ mdformat --check doc.md 
Error: File "/Users/bquorning/Code/mdformat-test/doc.md" is not formatted.

Then I install two plugins

❯ pip3 install mdformat-gfm==0.3.5 mdformat-footnote==0.1.1
[...]

The plugins are now known to mdformat:

❯ mdformat --version                                       
mdformat 0.7.14 (mdformat_tables: 0.4.1, mdformat_gfm: 0.3.5, mdformat_footnote: 0.1.1)

and now mdformat accepts the GFM syntax:

❯ mdformat --check doc.md
[no output]

It would be nice if I could enable plugins in the .mdformat.toml file. That would allow me to 1) not use all installed plugins by default, and 2) refuse to run if a required plugin is missing.

Footnotes

1. Code formatter plugins documentation ↩

2. Parser extension plugins documentation ↩

[hukkin]

Hi!

Currently mdformat CLI uses all installed plugins. There is no way to disable them.

You could use some tooling to run mdformat in a virtual environment with the correct plugins to achieve what you want. You could configure mdformat for pre-commit and run

pre-commit run mdformat --files <filename>

instead of

mdformat <filename>

or perhaps just create a virtual environment yourself

python3 -m venv venv
source venv/bin/activate
pip install mdformat-gfm mdformat-footnote
mdformat <filename>

Also tox and poetry are tools that should work here.

---

It would be nice if I could enable plugins in the .mdformat.toml file. That would allow me to 1) not use all installed plugins by default, and 2) refuse to run if a required plugin is missing.

We can consider this if there is a reason the aforementioned solutions are not acceptable.

[bquorning]

Yes, I am currently running mdformat inside Docker

FROM python:3.7-alpine
RUN pip install mdformat==0.7.14 mdformat-gfm==0.3.5 mdformat-footnote==0.1.1
ENTRYPOINT ["script/lint-markdown"]

(I need to exclude a few folders, which is why the entrypoint isn’t just mdformat .)

It’s just that when I opened a pull request to use mdformat at work, two colleagues immediately set out to install it locally (not via Docker) and ran into problems with GitHub Formatted Markdown.