Add a pre-commit hook to include additional formatting for Markdown

[gnawin]

Problem

Currently our hook is only markdown lint, that has limitations that I experienced wrt to tables. Markdown All in One is a great plug-in for tables, that will save us from lots of manual formatting. It would be great to add a hook (if available) to pre-commit to make sure everyone uses it to ensure consistency of style.

Investigation

Below is a comparison of the popular plug-ins for markdown formatting. We currently have markdown lint.

Tool	Table Formatting	Lint Support	Pre-commit hook
Prettier	Yes	Yes, but opinionated formatting	Yes
markdownlint	No	Yes, and highly customizable via rules	Yes
Markdown All in One	Yes	No	No (I submitted a feature request, and the developer suggested using Prettier yzhang-gh/vscode-markdown#1403)

Since the starting point of this discussion is to enable table formatting, Prettier and Markdown All in One are both suitable. And we want a pre-commit hook for that, Prettier becomes the best option of the three.

To make it work by "Format on save", Prettier needs to be set as a default formatter (which means markdown lint will not work). However, its formatting conflicts with markdown lint. Two main conflicts are spaces and indentation.

docs/src/features.md:45:1 MD030/list-marker-space Spaces after list markers [Expected: 1; Actual: 3]
docs/src/features.md:47:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 4]

According to the documentation of markdown lint, these are default choices that can also be altered.

Proposal

Supposing that we don't have a strong opinion on these, I propose to

• use Prettier (i.e., install the plug-in, and add this pre-commit hook for markdown files). Accordingly, markdownlint is not longer needed.
• if we still want to have all the checks by markdown lint in pre-commit, we can alter the default settings so at least it doesn't conflict with Prettier.

Any opinions? @clizbe @datejada @abelsiqueira

[gnawin]

I did some investigation on this:

• There is no pre-commit hook yet available for Markdown All in One. So I submitted a feature request.
• I found we can use Prettier (https://prettier.io/) to do the same. It is another generic code formatter but unfortunately, or fortunately, it does not support Julia yet. So maybe we can use Prettier for markdown formatting. There is a pre-commit hook for it. I'm a bit hesitating because maybe this is overkill as it may not be good to have two formatters at the same time. @abelsiqueira What do you think?

[abelsiqueira]

We are already using prettier for yaml and json, so that's actually pretty good. Thanks for checking and opening a feature request.

[gnawin]

@abelsiqueira Prettier indeed does Markdown formatting, but not exactly the same as the Markdown lint we have now. Keeping both for md files will lead to conflicts. If I understood you correctly, I can go forward with Prettier to replace our current Markdown lint?

[abelsiqueira]

I think we would need to see where they conflict with each other. Ideally you want the linter and formatter to work together, but that might be hard. Also, one of the advantages of Markdown All in One was the table formatter. Does prettier does something similar?
Also, maybe there are other markdown formatter options in pre-commit?

[gnawin]

I converted this issue into a discussion and added more information. What you do think?

[abelsiqueira]

Good idea. Then we can we get some input from @datejada and @clizbe

[abelsiqueira]

Looks like we have a decision to change to prettier 👍

[clizbe]

I agree we should just migrate to Prettier and drop Markdownlint. Good work, Ni! :)

[datejada]

I agree! Let's go for Prettier. Thanks @gnawin

[gnawin]

Great! Thanks everyone. I'll convert this to an issue and make sure this is covered also in Readme.dev.
Since this changes the current workflow slightly. I'll tag everyone on the PR next Monday so we can also discuss in-person if needed.

[gnawin]

Hey everyone @abelsiqueira @clizbe @datejada @suvayu @greg-neustroev @gzclarence , after PR #552 we use Prettier for markdown formatting instead of markdown lint.

Because Prettier is now also used in pre-commit, it is better that you configure Prettier also locally. To do so, please take a look at the instructions at README.dev.md -> installing software -> 7. Prettier

[clizbe]

I'm such a noob it took me a couple times to notice "Configure default formatter..." at the bottom of the list that drops down for "Format Document With..."
So if more people have the problem, we can add it to the ReadMe.Dev. 😅

[datejada]

It also took me a couple of clicks to figure it out. Also, the previous point is that the PNG needs to be formatted correctly. Is that what the PR #555 is fixing? @gnawin, also you can add something like this:

To do so, in VSCode, open any markdown file, right-click on any area of the file, choose "Format Document With...", and choose `Prettier` as the default formatter from the drop-down list at the top of the screen.

[clizbe]

Nah @datejada choosing Prettier from the dropdown won't set it as the default.
Something like click "Configure default formatter" from the drop-down list and choose Prettier.

[gnawin]

Hi both, thanks for the feedback, I'll add this:

To do so, in VSCode, open any markdown file, right-click on any area of the file, choose "Format Document With...", click "Configure Default Formatter..." situated at the bottom of the drop-list list at the top of the screen, and choose `Prettier- Code formatter` as the default formatter. Once you are done, you can double-check it by again right-clicking on any area of the file and choosing "Format Document With...", and you should see `Prettier - Code formatter (default)`.

And yes, PR #555 is fixing the PNG issue.

[gnawin]

Following my feature request of adding a pre-commit hook for Markdown All in One, the developer actually suggested using Prettier instead. yzhang-gh/vscode-markdown#1403