Markdown - why inserting raw html element in markdown document is not recommended?

Question

I used to write posts by markdown.

When I insert html elements in markdown document, markdownlint tell me that the document violates the markdown rule "MD033 - Inline html".

Rule "MD033 - Inline html" is triggered whenever raw HTML is used in a markdown document.

However, I don't know why inline html element is not allowed in markdown document.

I have searched it in google, but I can't find it.

If anyone who read this post know this, please let me know.

Always Thanks.

Answer 1

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".