markdown linter

[markus2330]

As suggested by @Namoshek we should use a markdown linter to automatically reformat markdown code.

In #1339 he said: "Maybe a linter (or another one) could help? Involves installing npm on the corresponding build-agents though."

In #1034 he said: "Searching for markdown formatters/validators isn't all that viable, but I found remark (nodejs based), which can reformat markdown files to a format that is widely accepted by many doc generators, etc. There are also plugins like remark-lint, which can be configured to throw warnings on style mistakes, but it seems that remark-lint is not (yet) able to fix style issues."

Work already done

(copied from #1339)

Did you look how many warnings are issued by remark-lint?

With my special configuration that enforces quite a lot of stuff (e.g. same list character everywhere, equal indentations, atx-closed headers, blablabla...), it was about 4200 warnings for all markdown files together. After formatting with remark, the warnings increased to about 4900. So my desired still is quite apart from the remark default.

Not sure if most/any of the settings are clear from their name, but that's what I used:

{
    "plugins": {
        "lint": {
            "blockquote-indentation": 2,
            "checkbox-character-style": {
                "checked": "x",
                "unchecked": " "
            },
            "checkbox-content-indent": true,
            "code-block-style": "indented",
            "definition-spacing": true,
            "fenced-code-marker": "`",
            "final-definition": true,
            "final-newline": true,
            "hard-break-spaces": true,
            "heading-increment": true,
            "heading-style": "atx-closed",
            "list-item-bullet-indent": true,
            "list-item-content-indent": true,
            "list-item-indent": "space",
            "list-item-spacing": true,
            "no-autolink-without-protocol": true,
            "no-blockquote-without-caret": true,
            "no-consecutive-blank-lines": true,
            "no-duplicate-definitions": true,
            "no-duplicate-headings": true,
            "no-emphasis-as-heading": true,
            "no-file-name-irregular-characters": true,
            "no-file-name-outer-dashes": true,
            "no-heading-content-indent": true,
            "no-heading-indent": true,
            "no-inline-padding": true,
            "no-literal-urls": true,
            "no-missing-blank-lines": {
                "exceptTightLists": true
            },
            "no-table-indentation": true,
            "no-tabs": true,
            "no-undefined-references": true,
            "table-cell-padding": "padded",
            "table-pipe-alignment": true,
            "table-pipes": true,
            "unordered-list-marker-style": "-"
        }
    }
}

If a setting is set to true, it normally means there is a check that warns if a situation described by the setting was found. E.g. no-heading-indent will warn if it finds something like ___## Blub (underscore symbolizes a space) because of the leading space.

Ok, with > 1000 warnings we cannot use it.

We certainly can, we only have to reformat the docu once. Running remark . --output in the repo root will fix all issues, but we can't really specify our desired format. The created format looks ok though (gist with three reformatted plugin READMEs, I don't think there is a difference in the parsed output on github, but the raw format is different (e.g. headlines, enumerations)).

Missing Work

• Reformat everything once
• describe format shortly, and describe how to reformat markdown
• write a reformat-markdown script
• Build Server Integration.
• Does it work with ronn? (e.g. does it destroy its description lists?)
• Does it work with doxygen?
• Is there some way to specify where it should not reformat?

Discussion

• Should we pursue a fully-automatic markdown formatting or is status quo better?

[dirkroorda]

Let linting specialize in detecting things that are mistakes, and leave all style related things to formatting. Remark-stringify formats a parsed markdown tree, but it could be improved by giving it more options.
So, the styleguides should move from a set of linter rules to a set of formatter options.

If your markdown comes out of a formatter that is always on, or works on save, suddenly those nitty-gritty details of how you want your markdown lose their importance. No matter how somebody else has writen the markdown, if you are going to interact with it, your formatter brings it in your style, you do your thing, and leave it like that. The next one does the same. No need to agree on formats anymore. And the readers of the actual content, for them it is moot anyway, because they look at the HTML.

[markus2330]

Thanks for the tips! Yes, linting actually implies searching for problematic parts.

The idea to reformat everything according to some style came from our experience with clang-format which decides on all formating problems good enough so that humans do not have to care about formatting anymore. Seems like we are not there yet for Markdown?

No need to agree on formats anymore.

Doesn't this clutter the commit history with formatting changes?

More concrete tips which linter to use and how to configure it are very welcomed.

[dirkroorda]

Ah, the commit histories ...
It seems that the AST is the real source, and the typed markdown is just a build product!
Coming from eslint and prettier, I would say: lint everything that is used but not defined.
Lint missing end markers for italics, bold etc, so everything where a piece of expected markup is missing.
And lint things that suggest something else is meant than written. Links with no url in it. Missing blank lines near headings and lists, etc.

[markus2330]

@sanssecours Is this resolved by #2422?

[sanssecours]

Is this resolved by #2422

Most of the points above should be resolved. The only thing left is probably:

• Is there some way to specify where it should not reformat?

. Ignoring certain parts of a Markdown file should be possible using

<!-- prettier-ignore -->

.

[markus2330]

Thank you! Could you please update the docu in doc/CODING.md (Markdown Section) to reflect that?