Make heading style formatting configurable

[arwedus]

Description / Summary

In our (big) project, we have the convention to format at least level 1 headings always with Setext (underline) - there is also always just one level 1 heading per document allowed. We leave it up to individual subprojects whether they want to consistently apply setext style headings for level 2 as well or whether they want to start using ATX headings there.

I kindly request a configuration option "first_atx_heading_level". Allowed values: (1, 2, 3). Default value: 1

Effect: All headings of level below and including "first_atx_heading_level" are formatted with ATX style. All levels above are consistently formatted with setext (underline).

Value / benefit

This would actually enable us to use your great program!
We have made the choice for Setext because a single # character is visually very unimpressive. Setext does an inversion: The lower the heading is, the more it stands out in the code. A single # can also be confused with the start of a line comment in many scripting languages. Last but not least, we use MyST-parser and sphinx, mostly, and we want to keep a little visual consistency with the restructuredtext domain.

Implementation details

No response

Tasks to complete

• Discuss and decide whether you accept this change in general.
• Please give feedback whether you would be interested in implementing this yourself, or provide some hints for implementation.

[hukkin]

Hey, thanks for the issue!

Firstly, a few things that I'll likely be repeating in every issue that asks for configuration 😄 : As a user and especially as a maintainer, I prefer an opinionated formatter with good defaults over a configurable formatter. The benefits are:

• As a user: no need for pointless arguments over which configurable style is better. Ideally only one decision to make: whether to use the formatter or not?
• As a maintainer: no need to maintain and test an endlessly growing matrix of configuration options. E.g. this change will slow down tests 3x, the next config knob will bump that up to 9x etc.

And yeah, there are a few config knobs already but I don't want any more unless for a very good reason.

I'll consider but please don't get your hopes up.

It should be fairly trivial to come up with something like a mdformat-setext plugin that does what you want. See the docs and some maybe some example plugin like mdformat-tables and feel free to ask questions about plugin development if you decide going down that road!

[jamesquilty]

@arwedus my context is similar to yours and the inability to configure mdformat blocks its use and has created additional work.

@hukkin I have some incomplete local hacks to configure mdformat to conform to my context and some development help to complete this would be appreciated. I'd be happy to contribute a plugin which provides a general configuration feature if it's technically possible.

[jamesquilty]

This Issue motivated me to complete my hacking, which I've pushed to a branch on my fork: add-defaults-to-configuration.

[arwedus]

@hukkin: I'm fine with a heading-formatter plug-in, but will most likely not have time to work on that this year.

I have some doubts about your argument that the number of tests required for n configuration options scales with n^2, though:

One could use the classification tree method after partitioning the configuration space in equivalence classes. I.e., in a test case that handles lists, or paragraphs, I do not have to test different configuration options for the heading as headings cannot appear in those blocks. One only needs to extend all tests that handle headings by an additional test for the output formatting. Not even the part that detects headings in the input needs to be covered by more tests than before.

[hukkin]

I think this should be implemented in a plugin.