Document new `mdformat-pyproject` plugin

[csala]

Context

I created this plugin that lets mdformat load options from a [tool.mdformat] section inside the pyproject.toml file, if it exists. This basically covers the need exposed in #356 without having to make any modification to the core of mdformat and therefore not binding the project to any particular project type.

The pyproject.toml file is found relative to each file that is processed, and relative to cwd if stdin contents are being parsed. This is the same behavior as with .mdformat.toml.

Also, if .mdformat.toml exists, its options are also loaded, giving precedence to the pyproject.toml ones if an option exists in both places (basically, .mdformat.toml is loaded first as usual, and then the pyproject.toml update whatever options were already loaded).

About the implementation

The implementation is slightly hacky, because it imports mdformat internals and forces the parsing and validation of CLI arguments twice in order to honor them, but I could not figure out a better way to achieve this without including some modification in mdformat to keep track of what the original CLI args were.

@hukkin If there is a cleaner or most robust way to achieve the same results I will happily hear that and adapt. Maybe #378 can also be considered along the way, so we can basically unify how the options and CLI arguments are handled in away that lets the plugins alter that if necessary (to either add options, or load the options from somewhere else).

Proposal

Add this plugin to the list in the docs. I'm happy to make a PR for that if this is accepted.

Tasks and updates

• [ ] discuss if we want to document this
• [ ] make a PR if positive

[hukkin]

Thanks for building the plugin! :partying_face:

If there is a cleaner or most robust way to achieve the same results I will happily hear that and adapt

I don't have the time right now, but might be able to have a look in the future.

I'm happy to make a PR for that if this is accepted.

A PR to add your plugin to the docs is very welcome! You may also want to consider adding this topic https://github.com/topics/mdformat to your project to make it more discoverable.

[csala]

Thanks @hukkin ! I'll try to make a PR adding the plugin sometime soon.

BTW: I just realized I forgot to link the plugin in the initial message. I just embedded it in the message, but here it is again for anyone looking for it:

https://github.com/csala/mdformat-pyproject