setup markdownlint

[HarshCasper]

Introduction

This PR introduces configuration files for markdownlint 1 and the related markdownlint-cli2 2. Additionally, we have introduced the custom Markdownlint rule max-one-sentence-per-line 3 to ensure that we adher to one-sentence-per-line rule going forward.

Ignored Rules

As part of this exercise, we opted to ignore a few rules, in the interest of time and effort. They are:

• MD029: Ordered list item prefix
• MD046: Code block style
• MD025: Single H1
• MD001: Header levels increment by one
• MD024: Multiple headers with the same content
• MD055: Inconsistent leading and trailing pipe characters
• MD056: Inconsistent Table column count
• MD036: Emphasis used instead of a header
• MD003: Header style
• MD033: Inline HTML
• MD013: Line length
• MD034: Bare URL used
• MD032: Lists should be surrounded by blank lines

We hope to progressively fix them over the time but they are not the current priority.

GitHub Action

This PR also introduces a GitHub Action 4 that runs only on changed files every pull request.

Pre-Commit Hook

This PR also introduces a Pre-commit hook to run the lint process locally to reduce the feedback cycle.

Next Steps

Service owners should review the docs that they own and report to us if Markdownlint has inadvertently made unexpected changes.

[github-actions]

🎊 PR Preview has been successfully built and deployed to https://localstack-docs-preview-pr-1382.surge.sh 🎊

[alexrashed]

It would be great if you could add a description to the PR such that reviewers can get an insight of what you want to accomplish with the changes here.

[HarshCasper]

@alexrashed — I was in the process of writing that :)

I hope the current description gives an idea of what we are looking to accomplish.

[alexrashed]

Awesome! Thanks for the detailed explanation! Automation / linting around our best practices has often proven to be very effective and helpful!

In other repositories we use pre-commit (there is an offical one for markdownlint), which helps contributors to get notified on issues in their files right when they commit the changes locally.
It would also be great if you could fix the last remaining issues in the code, if there's a lot we could also try to get codeowners on board?

And another tip on the side (which I think won't be necessary for this changeset): If you want to protect the Git history / blame views from being polluted by formatter changes, you can use .git-blame-ignore-revs to ignore specific commits (later on). However, for that you would have to separate the configuration of the linting tools from the actual formatting...

[HarshCasper]

Thank You @alexrashed for the feedback — I'll setup the pre-commit hook and revisit the .git-blame-ignore-revs later on 👍

[steffyP]

@HarshCasper: just as an FYI - all the coverage files are auto-generated (by the Update Parity Docs workflow) - I think we should either make sure that the workflow runs the format as well, or adapt the template for the file creation :)

[HarshCasper]

I will adapt the workflow to run the format as well 👍

[remotesynth]

I didn't go through all 336 changed files of course, but the preview looks fine and the additions seem fine as well.

[macnev2013]

Thanks for jumping on it. I've gone through my services. LGTM 🚀

[viren-nadkarni]

I recommend also verifying all changes yourself because not all pages have owners.

[viren-nadkarni]

Changes in this file are invalid

[steffyP]

Nice work! I think having this formatting in place will make things moving forward. 🚀

My only remarks left:

1. please add a note to the README regarding the pre-commit hook
2. please make sure that the workflow for updating parity docs still work - either trigger the workflow (against this branch), or after we merged this. Only want to make sure everything runs smoothly 🙂