GH Actions: add markdown lint + QA jobs

[jrfnl]

Description

Follow up on and depends on #449: this PR adds two markdown specific jobs to the validate workflow to ensure code style consistency and execute various QA checks, like a broken link and check and duplicate link check.

GH Actions: add new check for consistency in markdown files

This new check uses the NPM MarkdownLint-CLI2 package via the DavidAnson/markdownlint-cli2-action action runner from the same maintainer.

It executes a loose check for consistency and some common errors.
Some of the more annoying rules/rules which could impact display of markdown files on GitHub have been disabled.

All necessary configuration is contained in the .markdownlint-cli2.yaml file.

To run locally, install via:

npm install -g markdownlint-cli2

... and then run via:

markdownlint-cli2

Includes a problem matcher which should allow for displaying the results inline in GitHub PR code review view.

Includes adding node_modules to the .gitignore in case anyone would install these tools locally (to prevent them committing them).

Refs:

• https://github.com/DavidAnson/markdownlint
• https://github.com/DavidAnson/markdownlint-cli2
• https://github.com/marketplace/actions/markdownlint-cli2-action

GH Actions: add new check with additional QA for markdown files

While MarkdownLint is absolutely great for finding formatting issues, Remark offers some additional "rules" which are useful, such as checking that links and link definitions match up, verifying all used links work and some additional formatting checks which markdownlint just doesn't offer.

The rule configuration is contained in the .remarkrc file.

Files/directories to be ignored can be listed in the .remarkignore file which supports glob syntax, like .gitignore.
Note: .-prefixed files and directories are excluded by default. To include those in the scan, they have to be passed explicitly on the command-line.

To run locally, follow the same steps as per the GitHub actions workflow.

Note: the workflow contains a double-run of remark-lint to allow viewing the results both in a human readable way in the actions transscripts, as well as getting annotations for found issue in PRs.

Notes about the config:

• An extensive effort has been made to prevent duplication of messages between the Markdownlint and the Remark check. This includes ensuring there are no conflicting rules.
• As the changelog contain a large number of links, at some point the check may run into a rate limit. Excluding contributor links should prevent that for a while.
• The file name check does not allow for the file names GitHub requires for issue templates.
  The provided regex fixes that.
• The "undefined references" check doesn't natively understand arrays in frontmatter, nor the new "callout" syntax supported by GitHub.
  The provided config should prevent false positives for those.

Refs:

• https://github.com/remarkjs/remark/tree/main/packages/remark-cli
• https://github.com/remarkjs/remark-lint
• https://github.com/remarkjs/remark-gfm
• https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent
• https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended
• https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide

Additional (external) plugins included:

• https://github.com/vhf/remark-lint-heading-whitespace
• https://github.com/wemake-services/remark-lint-list-item-punctuation
• https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-match-punctuation
• https://github.com/olizilla/remark-lint-no-hr-after-heading
• https://github.com/remarkjs/remark-lint-no-dead-urls
• https://github.com/remarkjs/remark-validate-links

Suggested changelog entry

N/A

Related issues/external references

Loosely related to #244