Respect the original Markdown syntax

[mr-infty]

As it stands now, this VSCode plugin marks Markdown documents that comply with the original Markdown syntax. For example, MD007/ul-indent and MD004/ul-style directly contradict the original specification, which explicitly allows one to use "*", "+" and "-" interchangeably as list markers, as well as allowing you to indent lists up to three spaces.

I am aware that you can disable rules, but my point is that those rules shouldn't be there in the first place, since they are completely unnecessary and contradict the original spirit of Markdown.

[DavidAnson]

The document you link to gives this example of a valid ordered list:

3. Bird
1. McHale
8. Parish

But I think most people would agree it's silly to write like that and it's confusing for anyone reading it. So markdownlint warns about that syntax.

By their nature, linters can be opinionated and will sometimes recommend against patterns that are valid. As you note, individual rules can be disabled and that's what I recommend if you find value in patterns like the above. But if you find everything too bothersome, maybe this extension isn't for you. Some people get value from it, but I understand it's not for everybody. :)

[mr-infty]

Actually, it does not. The full quote is this (bold face is mine):

If you instead wrote the list in Markdown like this:

1. Bird

2. McHale

3. Parish
   or even:

4. Bird

5. McHale

6. Parish
   you’d get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

So according to "that document I linked", lists like

3. Bird
1. McHale
8. Parish

should not be valid.

But lazy list numbering isn't really the issue here at all.

The point is that Markdown is supposed to be a lightweight structured text format, that allows you to convert it to HTML or other formal structured documents. It therefore should not be more restrictive than necessary, that is why "that document I linked" explicitly allows indenting of lists, since that obviously helps readability.

Also, whether I like your linting rules or not is not the issue here. The issue is that the creator of Markdown explicitly allows what your linter marks as incorrect.

[DavidAnson]

Please read the passage you wrote again - it says 3/1/8 is a valid syntax that produces the same HTML output as 1/2/3. You can verify that with Gruber's dingus here https://daringfireball.net/projects/markdown/dingus

Again, markdownlint exists for people who want to impose additional restrictions on their Markdown, possibly for consistency or to avoid cross-parser problems related to the document you link being under-specified. You can read more about that here: https://commonmark.org/

There is no requirement to use this linter and I encourage you not to if it offends you. I hope it enables some people to write better Markdown, but accept that beauty is in the eye of the beholder.

[mr-infty]

Please let us focus on the orginal issue, which is this.

According to the rules of your linting marker, lists are not be be inlined. The original Markdown specification by its author John Gruber, which I cited, explicitly allows indentation of lists up to three spaces.

Yes, markdownlint and your linter of course impose rules not found in the original specification. But that is not the issue.
The issue is that this rule in your linter contradicts what is explicitly and clearly formulated in the original specification.

No specification is set in stone, and many do contain mistakes which should be rectified, not obeyed by. For example, the lazy numbering feature you mentioned seems worthy of discussion

But you haven't given any reason why the specific rule I mentioned, and which is the object of this issue, should be disregarded. On the contrary, I can give reasons why your rule is misguided.

Indenting a list

1. increases visual clarity, by separating the main body of the text from the list, which makes it easier to recognize it as a list,
2. establishes a hierarchy, by establishing the list as subordinate to the main text,
3. eases navigation and
4. gives a more professional appearance, as indeed many style guides recommend indenting enumerations.

Ironically, this very list is rendered indented by GitHub's renderer, making my point.

And visual appearance of Markdown source code is important, since it is not merely a format to specify visually appealing documents (like LaTeX), but which strives itself for visual clarity.

It is of course your linter, but you can't just make up any rule you want: if it is to be a linter of "Markdown", then it is bound by whatever is to be understood by that term. By introducing rules contradicting that understanding you risk

1. fragmentation of the Markdown user base,
2. confusion as to which rules apply,
3. compatibility issues,
4. loss of trust in your linter and the Markdown text format.

I therefore kindly ask you to consider making the aforementioned rules opt-in, rather than enabling them by default, or to remove them entirely.

[DavidAnson]

You say the markdownlint rule about list item indent contradicts the syntax at https://daringfireball.net/projects/markdown/syntax, but I don't think that's true.

Gruber's syntax document says this (and only this) about the topic: "List markers typically start at the left margin, but may be indented by up to three spaces." Notably, all the examples given there start at the left margin; none are indented. And that's exactly what rule MD007/ul-indent enforces: no indent for top-level unordered list items.

Specifically, the (unindented) sample lists from that document produce NO warnings from MD007 with the default configuration: https://dlaa.me/markdownlint/#%25m%23%20Issue%20363%0A%0A*%20%20%20Red%0A*%20%20%20Green%0A*%20%20%20Blue%0A

By default, the MD007 prefers the typical (both as described by the author and as seen in practice) behavior - and also allows customization for scenarios where different behavior is desired.

This approach seems entirely reasonable to me and consistent with the behavior of other linting tools. Again, if you don't agree with the defaults or the principle of this, you can customize rules, disable them, or just not use this tool.

[mr-infty]

Gruber's definition gives explicit permission to indent lists, your rule rules that invalid. So what Gruber explicitly allows you deny: that's a contradiction.

The use of the word "typically" here is explanatory rather than normative: it merely assures the reader that starting at the left margin is the common way. Indeed, if it was normative, the sentence would contradict itself.

Now, it would seem that there is no difference between enforcing rules contradicting the original specification and merely enforcing stricter rules, since in both cases you end up with the same thing, namely a smaller set of allowed texts. But this view misses the point.

A specification is not merely the set of all conforming instances, a specification also carries intent. It therefore does make a difference whether a linter disallows something that the spec allows as a consequence of general rules, or whether the inter disallows something that was explicitly allowed by a specific rule: in the second case you violate the spirit of the law, in the first case you don't.

There also does not seem to be any good reason to disallow indenting per se; it would be enough to ban inconsistent indenting.

[DavidAnson]

I appreciate your passion here.

As I stated before, markdownlint encourages people to write Markdown using a particular subset of all the possible syntax. (Much like how the CommonMark specification tries to add clarity to areas of ambiguity.) In some cases, this tool helps avoid unexpected behavior due to parser differences (ex: blank lines around lists). In some cases, it helps catch mistakes (ex: “backwards” links). In different cases, it encourages consistency and readability (ex: consecutive list item numbering). For something like list indent, the choice of how much indent to prefer is arbitrary, but was informed by common practice and is configurable.

It’s clear that you don’t want any of this and I respect that. However, there are many people who use this tool regularly and I think that’s because they find value in what it does.

Your feedback is heard, but I think it is more philosophical than practical. This tool is working as intended for an audience who want the kind of assistance it provides.

[mr-infty]

I appreciate your patience and I understand that it's your project and you are under no
obligation to justify your decisions, but I do have to rectify a few things.

First, I'm sorry if I have come across as not appreciating your linter at all; in fact I do.
For example, I do appreciate the correction of backwards links and stylistic mistakes such
as inconsistency of header formats. My sole complaint was and is about disallowing indentation of
lists, as it both contradicts the Markdown specification and its intent, expressed clearly by its
author in the following quote:

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

Readability, however, is emphasized above all else.

This brings me to the second correction I need to add, namely your claim that
my feedback is "philosophical" and (therefore?) impractical. Your linter is a widely used
plugin that advertises itself as a linter for "Markdown". As such, its choice of rules has
considerable influence in shaping the idea of what Markdown is. Adopting a rule that dimnishes
readability and violates the original intent of John Gruber thus has practical consequences
for the format itself (which I have elaborated). And my feedback was very concrete: to either

• remove this rule,
• disable it by default or to
• reform it, as to merely flag inconsistent indentation.

It would be a different matter if your linter would advertise itself as a linter of a particular
(that is definite and recognizable) variant of Markdown: in that case there would be no danger of
confusing the notion of what constitutes the base format itself.

I therefore kindly request that you reconsider your dismissal of my concerns as unpractical and recognize
the practical consequences of the issue I have raised.