Add linting information to CONTRIBUTING.md

This adds information on how the docs use linting, and more detailed
instructions on how to enable it in an IDE, using VSCode as a concrete
and widespread example.

Additionally, to do this, we add a duplicate style config for
markdownlint in JSON format for the Node.js implementation of
markdownlint that is used by various editor plugins. These both
implement the same core set of warnings, and appear to function
identically.

Author: jedevc

.markdownlint.json

@@ -0,0 +1,13 @@
+{
+  "default": false,
+  "hr-style": true,
+  "no-missing-space-atx": true,
+  "no-multiple-space-atx": true,
+  "no-missing-space-closed-atx": true,
+  "no-multiple-space-closed-atx": true,
+  "no-space-in-emphasis": true,
+  "no-space-in-code": true,
+  "no-space-in-links": true,
+  "ol-prefix": {"style": "ordered"},
+  "no-reversed-links": true
+}

.mdlrc.style.rb renamed to .markdownlint.rb

@@ -1,4 +1,7 @@
 # https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
+#
+# When updating rules in this file, ensure the corresponding rule list in
+# .markdownlint.json is also updated.
 
 # style
 rule 'header-style'

CONTRIBUTING.md

@@ -6,8 +6,8 @@ as possible for you to work in this repository. The documentation for Docker is
 ## Table of Contents
 
 - [Contribution guidelines](#contribution-guidelines)
-  - [Files not edited here](#files-not-edited-here)
   - [Important files](#important-files)
+  - [Files not edited here](#files-not-edited-here)
   - [Per-page front-matter](#per-page-front-matter)
 - [Pull request guidelines](#pull-request-guidelines)
 - [Collaborate on a pull request](#collaborate-on-a-pull-request)
@@ -192,7 +192,18 @@ repository. Compressing images after adding them to the repository actually wors
 
 ### Style guide
 
-Docker does not currently maintain a style guide. Follow the examples set by the existing documentation and use your best judgment.
+Docker does not currently maintain a style guide. Follow the examples set by
+the existing documentation and use your best judgment.
+
+We use [markdownlint](https://github.com/markdownlint/markdownlint) to ensure
+consistent markdown source, and to catch potential formatting issues as early
+as possible. While CI/CD will catch these during the PR review process, you may
+wish to configure your IDE to catch these while writing.
+
+For VSCode, you can use the [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
+plugin, which will automatically detect and apply the pre-made rules in
+`.markdownlint.json`. This plugin also comes with auto-fix functionality, see
+the plugin documentation for more information.
 
 ## Build and preview the docs locally
 

Dockerfile

@@ -82,7 +82,7 @@ FROM gem AS mdl-base
 ARG MDL_JSON
 ARG MDL_STYLE
 RUN --mount=type=bind,target=. <<EOF
-  mdl --ignore-front-matter ${MDL_JSON:+'--json'} --style=${MDL_STYLE:-'.mdlrc.style.rb'} $( \
+  mdl --ignore-front-matter ${MDL_JSON:+'--json'} --style=${MDL_STYLE:-'.markdownlint.rb'} $( \
     find '.' -name '*.md' \
       -not -path './registry/*' \
       -not -path './desktop/extensions-sdk/*' \