Guidance on Extending mdformat Configurability

[KyleKing]

Context

There are a number of issues and open PRs to extend mdformat's configurablability for various use cases: #318, #381, #391, #412, #400, #438, #437, #432, #431, #359 (comment), #428, #421, #268 (comment), #262, #234 (and executablebooks/mdformat-myst#9 (comment)), #331 (comment), #332, #378, #53 (comment), #283 (comment), #261 (comment), #50, etc.

In a number of instances @hukkin has reiterated the position that mdformat should only support the minimum amount of configuration (#283 (comment)). The recommended alternative is for users to implement plugins in order to change behavior. In doing so, we should be sure to document where users have successfully demonstrated extending mdformat configuration through plugins (such as: #356 (comment))

Proposal

There should be official documentation and/or guidance to clarify what kinds of configuration belong in mdformat vs. those that should be implemented as plugins. I believe this philosophy is strongly held and should be proactively communicated. PRs and issues should be reviewed and/or closed accordingly because some have been in limbo for years.

Tasks and updates

No response

[hukkin]

Thanks for the issue Kyle!

mdformat should only support the minimum amount of configuration

This is correct, and is one of the first things mentioned in the contributing docs.

The recommended alternative is for users to implement plugins in order to change behavior. In doing so, we should be sure to document where users have successfully demonstrated extending mdformat configuration through plugins

I've recently thought it may be best to reduce the amount of plugins we refer to in the docs to just a few essential ones like mdformat-gfm, and make it very clear the list is non-comprehensive. Then point to https://github.com/topics/mdformat for more.

I can't guarantee the quality or maintenance status of plugins other people develop so probably best not to "bless" any of them, or set false expectations of the comprehensiveness of the manually maintained plugin list.

There should be official documentation and/or guidance to clarify what kinds of configuration belong in mdformat vs. those that should be implemented as plugins. I believe this philosophy is strongly held and would should be proactively communicated.

It's hard to come up with a general rule that's always correct. I think 99% of all configurability belongs in a plugin, but when not it probably needs to be reviewed. Not sure where or how to document this more clearly than the contributing docs already do. Issue templates perhaps? Those we inherit from the organization and I honestly never evaluated whether they make any sense or no.

PRs and issues should be reviewed and/or closed accordingly because some have been in limbo for years.

Yeah, this would be ideal. It's probably better not to have much expectations for anything or anyone though. This is open source, and essentially, a hobby.

[KyleKing]

I'm glad to see so much activity again! (It has been hard to keep up!)

I've recently thought it may be best to reduce the amount of plugins we refer to in the docs to just a few essential ones like mdformat-gfm, and make it very clear the list is non-comprehensive. Then point to github.com/topics/mdformat for more.

I can't guarantee the quality or maintenance status of plugins other people develop so probably best not to "bless" any of them, or set false expectations of the comprehensiveness of the manually maintained plugin list.

That seems reasonable to me and would be one less source of maintenance work

There should be official documentation and/or guidance to clarify what kinds of configuration belong in mdformat vs. those that should be implemented as plugins. I believe this philosophy is strongly held and would should be proactively communicated.

It's hard to come up with a general rule that's always correct. I think 99% of all configurability belongs in a plugin, but when not it probably needs to be reviewed. Not sure where or how to document this more clearly than the contributing docs already do. Issue templates perhaps? Those we inherit from the organization and I honestly never evaluated whether they make any sense or no.

PRs and issues should be reviewed and/or closed accordingly because some have been in limbo for years.

Yeah, this would be ideal. It's probably better not to have much expectations for anything or anyone though. This is open source, and essentially, a hobby.

No, of course not. To clarify, my goal was to help onboard new maintainers who can point to clear guidelines for consistency when you're not available (to distribute the workload where possible). I missed the paragraph in Contributing, but I think that is the right place and is sufficient. A number of the issues and PRs that I listed have already been resolved (🚀) or pending input, so I'm going to close this ticket