Integrate Markdown Tutorials with Markdownlint.js

[jakubsvec001]

This issue originated in this pull request (2959).

In contributing pull requests to markdown tutorials (minor fixes, structural suggestions, and content suggestions), I began having issues with maintaining consistent markdown formatting. @bbatsov suggested the possibility of incorporating a markdown linter and @cuihtlauac expressed interest in exploring the pros and cons.

The following are notes I took while exploring options suggested by @bbatsov from the perspective of an external contributor:

"
@cuihtlauac @bbatsov I am new to contributing to a project as robust as this so am coming at this without preferences.

This morning, I played around with Markdownlint.js and Pandoc and pasted my notes below:

Notes:

• markdownlint.js has two different cli tools that need to be installed separately:
  • markdownlint-cli is the most common tool for lint-checking files, but it does not automatically fix issues
  • markdownlint-cli2 is a more advanced cli tool but it is not a replacement for markdownlint-cli. It provides a --fix flag for automaticaly applying fixes on fixable errors
• a .markdown.json configuration file can be used to customize behavior. The config file must be in the same directory the cli tool is called from or a -config flag and path/to/file must be provided. I wish the tool would recursively search parent directories for a config file but maybe that would be more frustrating for other scenarios. The issue from my perspective is that it gives a contributor one extra thing to think about so as not to run commands with incorrect configs.
• markdownlint.js does not support auto-fixing line breaks
• Pandoc has a line-length auto-fixing feature and seems robust (from my limited testing) in how it breaks/unbreak/rebreaks lines to a selected column-width

WORKFLOW 1: Contributor's responsibility
As an external contributor I expect to have to read a style guide and contribution criteria to conform to. I can also be expected to download any tools necessary for submission and run them. Suggestions for commons commands would be helpful in the style guide to set proper flags, either for finding the .markdownlint.json config or for supplying some configs through the command-line.

In this way, adding this step to a contributor's workflow would solve your issue by formatting downstream of the pull request. A github pull workflow can then validate proper formatting.

WORKFLOW 2: Transparently apply fixes before incorporating pull request
However, the above adds friction to a contributor's workflow. Another option is to solve this problem transparently by having a github workflow perform automatic fixes upon a pull request being accepted using markdownlint-cli, cli2, and pandoc. This, however, there may be edge cases that cause some text being unexpectedly modified without being checked by a human.

WORKFLOW 3: A combination of 1 and 2
A final option is to do both.

I'm sure there are other considerations I'm not accounting for, but I wanted to look into it and wrap my head around some options.

If you would like, I'd be happy to write a first draft of a .markdown.json config file as well as a boilerplate style guide with instructions for downloading markdownlint.js and pandoc, along with commands to run.
"

[bbatsov]

See also #2967. I think the default markdownlint configuration is pretty good overall, so I don't think it will need much changes (if any). Off the top of my head we'd probably want to decide:

• whether to enforce only - for unordered lists (as is generally recommended) or stick to the default which allows using * as well (because lots of people are used to them) and just enforces consistent usage within a document
• what line length we want to enforce

[bbatsov]

I'll mention here #3012 and #3013 that should solve this ticket.