From ebd4a33866098ce26a1426779b03812cf95efe35 Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Mon, 1 Aug 2022 11:47:39 +0100 Subject: [PATCH] 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. --- .markdownlint.json | 13 +++++++++++++ .mdlrc.style.rb => .markdownlint.rb | 3 +++ CONTRIBUTING.md | 15 +++++++++++++-- Dockerfile | 2 +- 4 files changed, 30 insertions(+), 3 deletions(-) create mode 100644 .markdownlint.json rename .mdlrc.style.rb => .markdownlint.rb (78%) diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000000..c34d35b462 --- /dev/null +++ b/.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 +} \ No newline at end of file diff --git a/.mdlrc.style.rb b/.markdownlint.rb similarity index 78% rename from .mdlrc.style.rb rename to .markdownlint.rb index 61c70e4406..35dd0922e4 100644 --- a/.mdlrc.style.rb +++ b/.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' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ffdf31150b..f6b2a56d0e 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/Dockerfile b/Dockerfile index 946b3657e9..52861e154b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -82,7 +82,7 @@ FROM gem AS mdl-base ARG MDL_JSON ARG MDL_STYLE RUN --mount=type=bind,target=. <