TOP005.md

TOP005 - Blanks around multiline HTML tags

Tags: html, blank_lines

Aliases: blanks-around-multiline-html-tags

The rule is triggered when a line containing only an opening or closing HTML tag is surrounded by anything other than a blank line or fenced code block.

<div class="lesson-note" markdown="1">
#### An optional title

A sample note box.

</div>

```markdown
<div class="lesson-note" markdown="1">

#### An optional title

A sample note box.

</div>
```

In the above example, the very first opening tag will trigger this rule, as the line immediately after it is not a blank nor a code block delimiter.

The first closing tag will not trigger this rule, as there is a blank line on each side.

The second opening tag will not trigger this rule, as it is surrounded by a fenced code block delimiter and a blank line, both of which are valid.

The same applies for the final closing tag, hence it will not trigger this rule either.

This rule is ignored for HTML within html, jsx, erb or ejs fenced code blocks, as these do not require being surrounded by blank lines.

```html
<div>
  <p>
    The linter will be perfectly happy with the HTML here, as we are using an html code block.
  </p>
</div>
```

```markdown
<div>
  <p>
    Since we are not using an html or jsx codeblock, this rule will be triggered. highlighting all four tags.
  </p>
</div>
```

Rationale

Due to the way markdown-it parses HTML blocks, until a blank line is reached, all contents following an HTML opening tag will be included in a single html_block token. This means the text content will not be parsed as their own tokens, thus not triggering any linting errors within them.

This means the following markdown would not trigger any lint errors, despite it being full of errors:

<div class="lesson-note" markdown="1">
#### This title should trigger the "blanks around headings" rule
1. [this should trigger the "descriptive links" rule](#rationale)
2. this should trigger the "lazy list numbering" rule
</div>

By enforcing blank lines or code block delimiters surrounding HTML tags, all HTML boxes' text content can be separated into the appropriate individual tokens, and parsed correctly to trigger any appropriate rule errors.

This will help reduce the chance that maintainers miss linting errors within HTML blocks that are not flagged due to the above.