markdownlint | Markdown lint tool | Code Analyzer library

Linters encourage best practices and are often more strict than the syntax rules and/or parser/compiler. Wikipedia states that "a linter, is a static code analysis tool used to flag programming errors, bugs, stylistic errors, and suspicious constructs."

While programming errors will cause things to break, stylistic errors may only be recognizable by looking at a document. Therefore, organizations often define a style guide that they require all contributors to a project to follow.

A style guide or manual of style is a set of standards for the writing, formatting and design of documents. ... A style guide establishes standard style requirements to improve communication by ensuring consistency both within a document, and across multiple documents. Because practices vary, a style guide may set out standards to be used in areas such as punctuation, capitalization, citing sources, formatting of numbers and dates, table appearance and other areas. The style guide may require certain best practices in usage, language composition, visual composition, orthography and typography.

Obviously, a linter is ideal for flagging anything that doesn't fit within an organization's style guide.

That said, some may only use a linter to flag programming errors and bugs, but not care about "stylistic errors," which will not change the behavior of the output. For example, a Markdown linter may require a blank line between a header and the paragraph that follows it, while Markdown does not strictly require a blank line in that location. If you don't have a style guide which requires the blank line, then you may not want your linter to enforce that blank line.

For this reason, linters are customizable. You can configure the linter to only run the subset of rules which match your style guide. Some rules may even accept different configuration options which alter what they consider to be acceptable.

Generally, a linter will default to a configuration that is common among most of its users. However, each organization may have minor tweaks here and there to make. Therefore, you may need to configure the linter you are using to meet your requirements.

So, why might a style guide (and by extention a linter) disallow inline raw HTML? It's hard to say. You would need to ask the people who authored those style guides. However, we can make a few guesses.

It could be that the style guide also requires that only very basic inline styling be done to the text of the document. Perhaps anything that is allowed is completely achievable with Markdown syntax. In that case, a linter rule which disallows inline raw HTML is an easy and effective way to enforce that requirement of the style guide.

Another consideration is the philosophy behind Markdown itself. As the creator of Markdown explains:

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

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

Raw HTML tags detract from that goal, and therefore many view them as undesirable in their Markdown documents. I suspect this is the reason why the linter defaults to this behavior, but you would need to ask the developers of the linter to be sure.

Of course, if that doesn't fit your needs, or you don't care so much about readability, then you are free to include as many raw HTML tags in your documents as you want. However, you will then need to also custom configure any linter you use so that it ignores rule "MD033".

You can use custom markdownlint configuration for a file by using the following syntax:

There's text for non-highlighted fenced blocks compliant with MD040. I'm not sure how much official in Markdown world that is but it is listed in Github's linguist languages.yml as supported highlighted (in fact non-highlighted) language.

Answering my own question as finally reached to the solution from VS Codes very helpful and great team (https://github.com/microsoft/vscode/issues/88936)

And this is how got closer to the source of the problem - got this strange behaviour, in a React Component.js file when I type the snippet ('clmi' in this case) - before the React Component File's return() statement, I get the expected behaviour. But if I type the snippet ('clmi') inside the return() statement, I dont get anything. i.e. the snippet does not give me the code completion option inside the return () statment.

The source was that VSCode was not recognizing this file to be a "javascriptreact" language type.

Solution was as below

In a React Component's .js file, try the tokens inspector via "F1 > Inspect TM Scopes" and position the cursor at those insert position. That will tell you the detected, embedded language. Depending on your grammar it might be a different language

And bleow is what I am getting.

So as you can see, this not JavaScript nor JavaScript React but the jsx-attr language. So now I had to target that type with vscode snippet

So now, I put the whole snippet in the jsx-attr type target file ~/.config/Code/User/snippets/jsx-attr.json

And now the custom snippets worked as expected.

I think you can resolve it by associating master with origin master like this:

This is a feature introduced in v1.5.0 of Markdown All in One. You can control it with setting markdown.extension.syntax.decorations.

In short: No.

GitHub's spec does not provide for breaking a row across lines. Of note is the description of rows:

Each row consists of cells containing arbitrary text, in which inlines are parsed, separated by pipes (|). A leading and trailing pipe is also recommended for clarity of reading, and if there’s otherwise parsing ambiguity. Spaces between pipes and cell content are trimmed. Block-level elements cannot be inserted in a table.

Of course, while that doesn't specifically support it, it also doesn't explicitly exclude breaking a row across multiple lines. However, notice that the syntax does not offer any way (outside of a line break) to define when one row ends and another row begins (unlike the header row, which requires a "deliminator row" to divide it from the body of the table). As you cannot define the division between rows, then the only way the parser can determine when one row ends and another begins is with a line break.

And then we have this issue:

The remainder of the table’s rows may vary in the number of cells. If there are a number of cells fewer than the number of cells in the header row, empty cells are inserted. If there are greater, the excess is ignored:

In other words, the parser can not count columns to determine if the next line is a continuation of the previous row or a new row.

Finally, elsewhere the spec states that:

A backslash at the end of the line is a hard line break:

There are some exceptions for specific types of content, but tables are not mentioned at all in the backslash escapes section of the spec and therefore do not fit any of those exceptions. Thus, using a backslash escape at the end of the line only reinforces the fact that the line ends a row, which is the opposite of your desired effect.

So, no, there is no way to wrap a table row across multiple lines.

For comparison consider MultiMarkdown, which had support for the same table syntax long before GitHub offered it. MultiMarkdown's documentation plainly states:

Cell content must be on one line only

This behavior matches PHP Markdown Extra, which first introduced the syntax. In fact, I'm not aware of any implementation of this specific table syntax which supports any way for one row to be defined on multiple lines.

Based on this post, the docs once specified the following but its been removed from the docs: