Add hack/markdownlint.sh and fix warnings

The script disables one rule and makes it clear how to disable others
in the future.  Unfortunately, mdl doesn't include a blacklist option.
You can either run all rules, or specify a list of rules.

Author: russellb

docs/api.md

@@ -154,7 +154,8 @@ details, etc.
     * *validation error* -- The provisioning steps found an error.
     * *provisioning* -- An image is being written to the host's disk(s).
     * *provisioning error* -- The image could not be written to the host.
-    * *provisioned* -- An image has been completely written to the host's disk(s). 
+    * *provisioned* -- An image has been completely written to the host's
+      disk(s).
     * *externally provisioned* -- Metal³ does not manage the image on the host.
     * *deprovisioning* -- The image is being wiped from the host's disk(s).
     * *inspecting* -- The hardware details for the host are being collected

docs/baremetalhost-states.md

@@ -1,6 +1,7 @@
 # BaremetalHost Provisioning States
 
-The following diagram shows the possible Provisioning State transitions for the BaremetalHost object:
+The following diagram shows the possible Provisioning State transitions for the
+BaremetalHost object:
 
 ![BaremetalHost ProvisioningState transitions](BaremetalHost_ProvisioningState.png)
 

docs/dev-setup.md

@@ -1,27 +1,26 @@
-Setup Development Environment
-=============================
+# Setup Development Environment
 
 ## Install the operator-sdk
 
 Follow the instructions in the Quick Start section of
-https://github.com/operator-framework/operator-sdk to check out and
+<https://github.com/operator-framework/operator-sdk> to check out and
 install the operator-sdk tools.
 
 ## With minikube
 
 1. Install and launch minikube
 
-   https://kubernetes.io/docs/setup/minikube/
+   <https://kubernetes.io/docs/setup/minikube/>
 
-3. Create a namespace to host the operator
+1. Create a namespace to host the operator
 
-    ```
+    ```bash
     kubectl create namespace metal3
     ```
 
-4. Install operator-sdk
+1. Install operator-sdk
 
-    ```
+    ```bash
     eval $(go env)
     mkdir -p $GOPATH/src/github.com/metal3-io
     cd $GOPATH/src/github.com/metal3-io
@@ -33,9 +32,9 @@ install the operator-sdk tools.
     kubectl apply -f deploy/crds/metal3_v1alpha1_baremetalhost_crd.yaml
     ```
 
-5. Launch the operator locally
+1. Launch the operator locally
 
-    ```
+    ```bash
     export OPERATOR_NAME=baremetal-operator
     export DEPLOY_KERNEL_URL=http://172.22.0.1/images/ironic-python-agent.kernel
     export DEPLOY_RAMDISK_URL=http://172.22.0.1/images/ironic-python-agent.initramfs
@@ -44,9 +43,9 @@ install the operator-sdk tools.
     operator-sdk up local --namespace=metal3
     ```
 
-6. Create the CR
+1. Create the CR
 
-    ```
+    ```bash
     kubectl apply -f deploy/crds/example-host.yaml -n metal3
     ```
 
@@ -57,7 +56,7 @@ is to be able to have some test data, use the test fixture provisioner
 instead of the real Ironic provisioner by passing `-test-mode` to the
 operator when launching it.
 
-```
+```bash
 operator-sdk up local --operator-flags "-test-mode"
 ```
 
@@ -74,8 +73,9 @@ your environment.
 
 ## Using libvirt VMs with Ironic
 
-In order to use VMs as hosts, they need to be connected to [vbmc](https://docs.openstack.org/tripleo-docs/latest/install/environments/virtualbmc.html) and
-the `bootMACAddress` field needs to be set to the MAC address of the
+In order to use VMs as hosts, they need to be connected to
+[vbmc](https://docs.openstack.org/tripleo-docs/latest/install/environments/virtualbmc.html)
+and the `bootMACAddress` field needs to be set to the MAC address of the
 network interface that will PXE boot.
 
 For example:
@@ -98,7 +98,7 @@ registering a host. It takes as input the name of the `virsh` domain
 and produces as output the basic YAML to register that host properly,
 with the boot MAC address and BMC address filled in.
 
-```
+```bash
 $ go run cmd/make-virt-host/main.go openshift_worker_1
 ---
 apiVersion: v1
@@ -125,16 +125,17 @@ spec:
 
 The output can be passed directly to `oc apply` like this:
 
-```
-$ go run cmd/make-virt-host/main.go openshift_worker_1 | oc apply -f -
+```bash
+go run cmd/make-virt-host/main.go openshift_worker_1 | oc apply -f -
 ```
 
 When the host is a *master*, include the `-consumer` and
 `-consumer-namespace` options to associate the host with the existing
 `Machine` object.
 
-```
-$ go run cmd/make-virt-host/main.go -consumer ostest-master-1 -consumer-namespace openshift-machine-api  openshift_master_1
+```bash
+$ go run cmd/make-virt-host/main.go -consumer ostest-master-1 \
+  -consumer-namespace openshift-machine-api  openshift_master_1
 ---
 apiVersion: v1
 kind: Secret
@@ -166,8 +167,9 @@ spec:
 The `make-bm-worker` tool may be a more convenient way of creating
 YAML definitions for workers than editing the files directly.
 
-```
-$ go run cmd/make-bm-worker/main.go -address 1.2.3.4 -password password -user admin worker-99
+```bash
+$ go run cmd/make-bm-worker/main.go -address 1.2.3.4 \
+  -password password -user admin worker-99
 ---
 apiVersion: v1
 kind: Secret

docs/publishing-images.md

@@ -11,7 +11,7 @@ your development fork.
 2. Set up your account on [quay.io](https://quay.io).
 3. Link your repository from step 1 to quay.io by following the
    instructions to "Create New Repository" from
-   https://quay.io/repository/
+   <https://quay.io/repository/>
 
    1. Enter the quay.io repository name. It is good practice to use
       the same name as the github repo.

docs/testing.md

@@ -6,32 +6,33 @@ The user running the tests must have permission on the cluster to
 create CRDs. An example role binding setting for configuring the
 "developer" user is provided in test/e2e/role_binding.yaml
 
-```
+```bash
 oc --as system:admin apply -f test/e2e/role_binding.yaml
 ```
 
 ### Run the e2e tests
 
 Run the tests using the operator-sdk command line tool
 
-```
+```bash
 operator-sdk test local ./test/e2e --namespace operator-test --up-local --debug
 ```
 
 If the setup steps above have already been run, causing "X already
 exists" errors, use the --no-setup option to skip that step in the test.
 
-```
+```bash
 operator-sdk test local ./test/e2e --namespace operator-test --up-local --debug --no-setup
 ```
 
 The tests can also be run via `make`
 
-```
+```bash
 make test
 ```
 
 Run linters test before pushing your commit
-```
+
+```bash
 make lint
 ```

hack/markdownlint.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+set -eux
+
+IS_CONTAINER=${IS_CONTAINER:-false}
+
+if [ "${IS_CONTAINER}" != "false" ]; then
+  TOP_DIR="${1:-.}"
+  find "${TOP_DIR}" -path ./vendor -prune -o -name '*.md' -exec \
+      mdl --style all --warnings \
+      --rules "MD001,MD002,MD003,MD004,MD005,MD006,MD007,MD009,MD010,MD011,MD012,MD013,MD014,MD018,MD019,MD020,MD021,MD022,MD023,MD024,MD025,MD026,MD027,MD028,MD030,MD031,MD032,MD033,MD034,MD035,MD036,MD037,MD038,MD039,MD040,MD041" \
+      {} \+
+else
+  podman run --rm \
+    --env IS_CONTAINER=TRUE \
+    --volume "${PWD}:/workdir:ro,z" \
+    --entrypoint sh \
+    --workdir /workdir \
+    registry.hub.docker.com/pipelinecomponents/markdownlint:latest \
+    /workdir/hack/markdownlint.sh "${@}"
+fi;
+
+# $ mdl --style all -l
+# MD001 - Header levels should only increment by one level at a time
+# MD002 - First header should be a top level header
+# MD003 - Header style
+# MD004 - Unordered list style
+# MD005 - Inconsistent indentation for list items at the same level
+# MD006 - Consider starting bulleted lists at the beginning of the line
+# MD007 - Unordered list indentation
+# MD009 - Trailing spaces
+# MD010 - Hard tabs
+# MD011 - Reversed link syntax
+# MD012 - Multiple consecutive blank lines
+# MD013 - Line length
+# MD014 - Dollar signs used before commands without showing output
+# MD018 - No space after hash on atx style header
+# MD019 - Multiple spaces after hash on atx style header
+# MD020 - No space inside hashes on closed atx style header
+# MD021 - Multiple spaces inside hashes on closed atx style header
+# MD022 - Headers should be surrounded by blank lines
+# MD023 - Headers must start at the beginning of the line
+# MD024 - Multiple headers with the same content
+# MD025 - Multiple top level headers in the same document
+# MD026 - Trailing punctuation in header
+# MD027 - Multiple spaces after blockquote symbol
+# MD028 - Blank line inside blockquote
+# MD029 - Ordered list item prefix - DISABLED
+# MD030 - Spaces after list markers
+# MD031 - Fenced code blocks should be surrounded by blank lines
+# MD032 - Lists should be surrounded by blank lines
+# MD033 - Inline HTML
+# MD034 - Bare URL used
+# MD035 - Horizontal rule style
+# MD036 - Emphasis used instead of a header
+# MD037 - Spaces inside emphasis markers
+# MD038 - Spaces inside code span elements
+# MD039 - Spaces inside link text
+# MD040 - Fenced code blocks should have a language specified
+# MD041 - First line in file should be a top level header
+# MD046 - Code block style - DISABLED