Verify Markdown documents in linting workflow

Also re-order to perform shellcheck first because it
requires the least installation work compared to pylint
and markdownlint.  The reason being if we're going to fail
during shellcheck, then we fail faster (and leave heavier
tasks for further down the line).

.github/workflows/analysis.yml

@@ -11,14 +11,21 @@ jobs:
         with:
           fetch-depth: 1
       - run:  sudo apt-get update
+      - name: Run shellcheck
+        run:  ./scripts/verify-bash.sh
       - name: Install pylint
         run:  |
           sudo apt-get install python3-setuptools
           sudo pip3 install pylint beautifulsoup4 html5lib
       - name: Run pylint
         run:  ./scripts/verify-python.sh
-      - name: Run shellcheck
-        run:  ./scripts/verify-bash.sh
+      - name: Install markdownlint
+        run:  |
+          sudo apt-get install ruby
+          sudo gem install mdl
+          sudo chmod go-w /usr/share/rust/.cargo/bin
+      - name: Run markdownlint
+        run:  ./scripts/verify-markdown.sh
 
   build_clang_static_analyser:
     name: Clang static analyzer

scripts/verify-markdown.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+# Copyright (C) 2020  Kevin Croft <krcroft@gmail.com>
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+# Based on `verify-bash.sh` by Patryk Obara <patryk.obara@gmail.com>
+# Copyright (C) 2019 licensed GPL-2.0-or-later
+#
+# This script exists only to easily run mdl (markdownlint) on all
+# *.md files in the repo.
+#
+# You can pass additional parameters to this script itself, e.g.:
+#
+#   ./verify-markdown.sh --verbose --json
+
+set -euo pipefail
+
+list_markdown_files () {
+	git ls-files | grep '.md$'
+}
+
+main () {
+	mdl --version
+	echo "Checking files:"
+	list_markdown_files
+	list_markdown_files | xargs -L 1000 mdl "$@"
+}
+
+>&2 main "$@"