Configure and apply markdownlint

[kachkaev]

@jwoLondon WDYT of using https://github.com/DavidAnson/markdownlint as an extra linter? It supplements Prettier and helps us keep markdowns a bit cleaner semantically (Prettier only works with syntax).

[jwoLondon]

Are you suggesting we just use it internally for consistent formatting of content we share in the litvis repo, or that we encourage/mandate for litvis users?

[jwoLondon]

This looks good and should help us to create consistent and accessible markdown.

Perhaps we should also disable MD013 (long line length), as we sometimes use bulleted lists with multiple sentences that get picked up by the linter.

Otherwise, I agree on disabling first line headings (css and hidden elm blocks commonly used before first heading). And agree also on disabling no-inline-html (sometimes use subscripts/superscripts and sometimes html img where we can control image dimensions).

I have no strong feelings about no-duplicate heading and no-emphasis as heading, but presumably you have examples where these are necessary.

[jwoLondon]

Have just noticed that the linter picks up MD004 'unordered list style' for lists that alternate between - and *. This is what Prettier inserts when we wish to have blank lines between list items. Is it better to use consistent list symbols and accept having no blank lines between items (subject to css styling), or do we drop this condition from the linter?

[jwoLondon]

I think we should also modify MD026, trailing punctuation in heading, so that question marks are allowed.

"MD026": { "punctuation": ".,;:!"}

[kachkaev]

Hi Jo! I'm at work now, so can't respond to emails – only seeing github notifications on my work laptop. WRT the rules we want to pick, I'm happy with any set – whatever you find convenient.

You'll notice that in this PR I'm extending @kachkaev/markdownlint-config – this is what I use in own projects (see index.json).

Perhaps, we don't need this extra abstraction in litvis and are better off without extending any third party config. In the future, when the set of rules you prefer settles, we can publish @gicentre/markdownlint-config and this will be the recommend starting point for giCentre projects.

In this PR, I mainly focus on adding the tool to the process, finding an ideal set of rules is out of scope. If you thing Markdownlint useful in principle, feel free to push any changes to this branch and merge. You'll probably want to install https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint too for a better local UX.

[kachkaev]

Using suppress-exit-code here so that it was possible to commit changes even if there are markdownlint issues. We can remove this later when we are sure that markdowlint is a must-have tool in this repo.

[kachkaev]

Hi Jo, the PR is ready for another review – thanks for your comments.

I also replaced ```md with ```markdown, because github syntax highlighter treats md as Matlab code or something.

Difference: before / after