Integrate with Markdown Linters about mdformat HOT 11 CLOSED

Hey @jamesquilty , thanks for the issue!

I have personally never used either of the markdownlint implementations so don't know much about them. Have you perhaps tried running both markdownlint and mdformat against some lengthy and/or feature-rich piece of Markdown code? Are you aware of what the possible style clashes are?

It seems like at least the Ruby implementation of markdownlint is very configurable (https://github.com/markdownlint/markdownlint/blob/master/docs/configuration.md). If there are lots of style clashes, I'm thinking the easiest way to achieve support between markdownlint and mdformat might be simply providing a compatible markdownlint configuration in mdformat documentation. If the styles are already very similar but not exactly, we could consider changing mdformat style accordingly.

from mdformat.

@hukkinj1 Thanks for the reply. I looked at your code and saw that you're taking a very different approach to formatting than I anticipated, accomplishing the formatting by processing the text to be formatted with markdown-it (IIUC). It appears that that method won't be compatible with the way markdownlint operates, due to the configurability of markdownlint.

While I'll be happy to be told that's not the case, I think it would be too much work to implement an arbitrary markdown formatter even with the example provided by markdown-it.

from mdformat.

I looked at your code and saw that you're taking a very different approach to formatting than I anticipated, accomplishing the formatting by processing the text to be formatted with markdown-it (IIUC)

Yes, what mdformat does is it parses the Markdown using markdown-it-py Markdown parser. markdown-it-py outputs a token stream that is for the most parts abstract syntax (most style choices are not present in this data anymore). Using this token stream as input, mdformat then re-renders the Markdown document, applying its own style choices.

I think it would be too much work to implement an arbitrary markdown formatter even with the example provided by markdown-it.

I'm not sure I understand what you mean by "arbitrary formatter" here.

from mdformat.

It appears that that method won't be compatible with the way markdownlint operates, due to the configurability of markdownlint.

I am also not sure why this would be the case?
I see this as an equivalent compatibility as Black Python formatting with flake8/pylint which work fine together.

from mdformat.

Closing this as stale. I believe both markdownlint tools mentioned here are configurable enough that they can coexist with mdformat so it's not clear to me what the issue is.

from mdformat.

@hukkin Thanks for following-up, it has been a while! I did some tests some time ago and then had to set it aside due to time pressures. To be absolutely clear, the issue is the other way around: how to configure mdformat so that it will coexist with an existing set of tools and style.

I installed with pip install mdformat-gfm and ran on a couple of sample Markdown files which passed markdownlint. I noted that mdformat:

1. changed the unordered list marker* to -
2. escaped all occurrences of [ and ] which aren't part of a link, e.g. my reference format [1] becomes \[1\] (raised here as #112).

From the mdformat style guide consecutive ordered and unordered lists will alternate between two different markers (edit to add: this was introduced by #83), which violates markdownlint rule MD004 - Unordered list style default consistent (but may pass sublist if mdformat's definition of "consecutive list" is the same as markdownlint's definition of "nested list) and rule MD029 - Ordered list item prefix.

I will want to configure mdformat to eliminate all of these problems because, it's not reasonable or feasible for me to reformat my Markdown files, configure markdownlint, my editors, and other tools, and generate a large number of commits just to conform to mdformat.

I did notice that mdformat handled raw HTML in Markdown files gracefully, which was definitely a plus!

I'd really like it if mdformat could be configured so it will integrate with an existing environment. Would that be possible?

from mdformat.

Generally speaking, it is not a design goal for mdformat to be configurable. Quite the opposite actually.

Regarding the problems you had:

From the mdformat style guide consecutive ordered and unordered lists will alternate between two different markers (edit to add: this was introduced by #83), which violates markdownlint rule MD004 - Unordered list style default consistent

mdformat only uses - as list marker under normal operation. It only alternates if there are two consecutive lists in the markdown with no other content in between. Note that it is not possible to express this Markdown in any other way (besides resorting to raw HTML). Were mdformat to convert the list item markers to be "consistent", it would turn two separate lists into one, and change semantics of the docuemnt. I'd argue that if markdownlint's consistent setting clashes with this, then that is an issue with markdownlint and should be fixed there.

Regarding escaping of [ and ] you'll find my thoughts in #112

from mdformat.

Thanks for the extraordinarily prompt reply, it's very much appreciated! I don't feel that there's an issue with markdownlint, we're talking about style and it's not something that should be argued over. I appreciate the motivation behind your design goal!

Unfortunately, this isn't a situation analagous to black & pylint where there's a single mandated style guide which allows black to be "opinionated" and "stubborn" (i.e. it defines a style which can not [easily] be configured) and not conflict with pylint. [Most of the time. I've had the not-very-fun situation where black and pylint conflict in pre-commit]. There's no single "correct" Markdown style, which is clearly the reason you've ended up writing multiple versions to "support" different styles: CommonMark, GFM and MyST.

In this context, I think it's reasonable to be "opinionated but not stubborn" and to allow some configuration. Which brings me to my original request for integration with Markdown linters: "If they are going to be coupled, it's really important that the formatter and linter work together and don't conflict."

from mdformat.

I don't feel that there's an issue with markdownlint, we're talking about style and it's not something that should be argued over.

We are not talking about style however.

Consider the following markdown

- item1
+ item2
- item3

If you render this as HTML you'll notice that there are three lists with one item in each. Now if I decide that for "consistency" I format it in a way that only - is used as list item marker, then suddenly we have only one list with three items in it. Semantics have changed, not only style. Mdformat will not change semantics, you'll have to do that manually.

There's no single "correct" Markdown style, which is clearly the reason you've ended up writing multiple versions to "support" different styles: CommonMark, GFM and MyST.

The ones you listed have nothing to do with formatting styles. They are three separate markup language specifications, and as such need to be parsed in a different manner.

Which brings me to my original request for integration with Markdown linters: "If they are going to be coupled, it's really important that the formatter and linter work together and don't conflict."

Then I'll need a concrete example where the two tools do conflict and what needs to be changed for them not to.

from mdformat.

I'd like to concentrate, please, on the most significant issue with mdformat which troubles me: it's not reasonable or feasible for me to reformat my Markdown files, configure markdownlint, my editors, and other tools, and generate a large number of commits just to conform to mdformat's style configuration.

If mdformat is "stubborn" about its style configuration, for example only using - as list marker, then that imposes a significant workload burden on me. I'm not sure that the benefits of adopting mdformat outweigh the costs!

I'd really like it if mdformat could be configured so it will integrate with an existing environment.

from mdformat.

Sure thing, but mdformat is an opinionated formatter and as a maintainer I'm not willing to test and maintain conf options based on opinions other than what the tool has. We have some configuration (ordered list numbering style, word wrap options) but I try to avoid adding more. New options will only be added for very good reasons. Simply "I prefer asterisk to dash" isn't a good reason here unfortunately. If you have a concrete proposal I'll be happy to discuss it in a separate issue.

In case you need a more configurable tool, the license is MIT, so you can fork and do whatever changes you wish, as long as you keep the license.

from mdformat.