Markdown Linting: remark-lint

Ensuring that documentations and content written in Markdown [1] are of
great quality should be a continuous goal of any project.
Persisting information is a consistent and extensive way helps tp keep a
project healthy, no matter whether for long-time or new users ad well as
maintainers and contributors. Linting Markdown results in better
rendering with different markdown parsers and makes sure less
refactoring is needed afterwards.

The best solution for this task would be a tool written in Go [2],
but the undisputed best tool is still remark-lint [3] which is
(unfortunately) written in JavaScript and used via NodeJS [4].
Of course there are fantastic projects written in Go like goldmark [5]
that provides a great way to _parse_ content, but linting is (currently)
not a feature.
remark-lint on the other side is built on top of remark [6],
the powerful Markdown processor powered by plugins (such as remark-lint
itself) and part of the unifiedjs [7] collective. It comes with really
large set of customizable rule [8] and ways to ensure Markdown will be
consistent across any project.

Another decision point for remark-lint was the fact that Prettier has
been added in GH-13 to this template so Node is already a development
dependency anyway. This also allows to add other awesome projects that
are (unfortunately) written in JavaScript and for which there is no
comparable alternative.

>>> Configuration

remark-lint can be used via remark-cli [npm-rcli] and a rule preset.
This preset is remark-preset-lint-arcticicestudio [10], my custom preset
that implements my Markdown Style Guide [11].
Since the custom preset is still in major version `0` the version range
is `>=0.x.x <1.0.0` to avoid the "SemVer Major Zero Caveat".
When defining package versions with the the carat `^` or tilde `~` range
selector it won't affect packages with a major version of `0`. Yarn will
resolve these packages to their exact version until the major version is
greater or equal to `1`.
To avoid this caveat the more detailed version range `>=0.x.x <1.0.0`
is used to resolve all versions greater or equal to `0.x.x` but less
than `1.0.0`. This will always use the latest `0.x.x` version and
removes the need to increment the version manually on each new release.

The `.remarkrc.js` configuration file is placed in the project root as
well as the `.remarkignore` file to also define ignore pattern.

>>> Package Script

To allow to run the Markdown linting separately a `lint:md` package
script has been added and included in the main `lint` script flow.

[1]: https://en.wikipedia.org/wiki/Markdown
[2]: https://go.dev
[3]: https://github.com/remarkjs/remark-lint
[4]: https://nodejs.org
[5]: https://github.com/yuin/goldmard
[6]: https://remark.js.org
[7]: https://unifiedjs.com
[8]: https://github.com/remarkjs/remark-lint/blob/master/doc/rules.md
[9]: https://www.npmjs.com/package/remark-cli
[10]: https://github.com/arcticicestudio/remark-preset-lint-arcticicestudio
[11]: https://arcticicestudio.github.io/styleguide-markdown

GH-15

.remarkignore

@@ -0,0 +1,6 @@
+# Copyright (c) 2020-present Sven Greb <[email protected]>
+# This source code is licensed under the MIT license found in the LICENSE file.
+
+# Important: Directories must have no "asterisk" wildcard character at the path end,
+# otherwise the pattern won't match!
+**/node_modules/

.remarkrc.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2020-present Sven Greb <[email protected]>
+ * This source code is licensed under the MIT license found in the LICENSE file.
+ */
+
+/**
+ * The configuration for remark-lint.
+ *
+ * @see https://github.com/remarkjs/remark-lint
+ */
+module.exports = {
+  plugins: ["remark-preset-lint-arcticicestudio"],
+};

package.json

@@ -21,10 +21,12 @@
     "format": "run-s format:pretty",
     "format:pretty": "prettier --write .",
     "lint": "run-s lint:*",
+    "lint:md": "remark --no-stdout . \".github/**/*.md\"",
     "lint:pretty": "prettier --check ."
   },
   "devDependencies": {
     "npm-run-all": "^4.1.5",
-    "prettier": "^2.0.5"
+    "prettier": "^2.0.5",
+    "remark-preset-lint-arcticicestudio": ">=0.3.0 <1.0.0"
   }
 }