Atom markdown warnings

Question

Using Atom 1.17.0 x64, editing Markdown with

given:

# Header

- list item

# Header 2

  - list item 2

---

Atom "remark-lint" gives me conflicting warnings.

Incorrect list-item indent: add 2 spaces (remark-lint:list-item-indent)

Incorrect indentation Before bullet: remove 2 spaces (remark-lint:lint-item-bullet-indent)

What am I doing wrong?

Answer 1

You are indenting your list item by two spaces instead of four or zero. While most Markdown parsers will do what you expect with less than four spaces of indent for a nested list, it can become ambiguous, especially if the number of spaces per level is not consistent.

Is your "list item 2" intended to be a root level list item? If so, then it should not be indented. Or it is intended to be part of a code block (perhaps demonstrating Markdown syntax of a list item)? Then it should be indented four spaces. Your intention is not clear, so the linter is giving you both errors and allowing you to chose which to address based on your intention.

For example, while the indented list item obviously does not have a parent list item (a header is not a list item), I missed that as first glance and assumed it was intended to be nested under the previous item. In other words, your two spaces of indent has introduced ambiguity.

Linters encourage 'best practices', not just 'good enough'. As the rules do not explicitly state that less than four spaces are allowed, the linter strictly enforces the four space rule, even if the parser does not. So, the 'best practice' is to only ever use indention in four space increments. That is what the linter expects.

For reference, here's the relevant part of the rule:

List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab...

To put a code block within a list item, the code block needs to be indented twice — 8 spaces or two tabs...