diff --git a/.github/workflows/validate-markdown.yaml b/.github/workflows/validate-markdown.yaml
index fd0b0c8..5b87c99 100644
--- a/.github/workflows/validate-markdown.yaml
+++ b/.github/workflows/validate-markdown.yaml
@@ -1,10 +1,9 @@
 name: validate-markdown
 
-# Author: @MikeRalphson
-# Issue: https://github.com/OAI/OpenAPI-Specification/issues/2130
+# Author: @ralfhandl based on work of @MikeRalphson
 
 #
-# This workflow validates files in the versions directory matching 1.*.md
+# This workflow validates markdown files in the `versions` directory matching *.md
 #
 
 # run this on push to any branch and creation of pull-requests
@@ -16,9 +15,16 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2 # checkout repo content
-    - uses: actions/setup-node@v1 # setup Node.js
+    - uses: actions/checkout@v4 # checkout repo content
       with:
-        node-version: '18.x'
+        fetch-depth: 0
+    # - name: use the javascript environment from main
+    #   run: |
+    #     git checkout remotes/origin/main -- package.json package-lock.json .markdownlint.yaml
+    - uses: actions/setup-node@v4 # setup Node.js
+      with:
+        node-version: '20.x'
     - name: Validate markdown
-      run: npx mdv versions/1.*.md
+      run: npx --yes mdv ./versions/[1-2].*.md
+    - name: Lint markdown
+      run: npx --yes markdownlint-cli --config .markdownlint.yaml versions/1.0.[^0].md versions/1.[1-9].*.md versions/2.*.md
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
new file mode 100644
index 0000000..3f95ad4
--- /dev/null
+++ b/.markdownlint.yaml
@@ -0,0 +1,12 @@
+# Unordered list indentation
+MD007:
+  indent: 2
+
+MD012: false # allow blank lines
+
+MD013:
+  line_length: 800
+  tables: false
+
+MD024: false # duplicate headings
+MD033: false # inline HTML
diff --git a/package-lock.json b/package-lock.json
index a93537f..45a5e79 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -18,6 +18,7 @@
             "devDependencies": {
                 "@hyperjump/json-schema": "^1.9.9",
                 "c8": "^10.1.2",
+                "markdownlint-cli": "^0.42.0",
                 "mdv": "^1.3.4",
                 "vitest": "^2.1.3",
                 "yaml": "2.4.2"
@@ -1584,6 +1585,16 @@
                 "node": ">=0.1.90"
             }
         },
+        "node_modules/commander": {
+            "version": "12.1.0",
+            "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
+            "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=18"
+            }
+        },
         "node_modules/concat-map": {
             "version": "0.0.1",
             "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
@@ -1702,6 +1713,16 @@
                 "node": ">=6"
             }
         },
+        "node_modules/deep-extend": {
+            "version": "0.6.0",
+            "resolved": "https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz",
+            "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=4.0.0"
+            }
+        },
         "node_modules/define-lazy-prop": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/define-lazy-prop/-/define-lazy-prop-2.0.0.tgz",
@@ -2187,6 +2208,19 @@
                 "node": "6.* || 8.* || >= 10.*"
             }
         },
+        "node_modules/get-stdin": {
+            "version": "9.0.0",
+            "resolved": "https://registry.npmjs.org/get-stdin/-/get-stdin-9.0.0.tgz",
+            "integrity": "sha512-dVKBjfWisLAicarI2Sf+JuBE/DghV4UzNAVe9yhEJuzeREd3JhOTE9cUaJTeSa77fsbQUK3pcOpJfM59+VKZaA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=12"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
         "node_modules/get-stream": {
             "version": "5.2.0",
             "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz",
@@ -2416,6 +2450,16 @@
             ],
             "license": "BSD-3-Clause"
         },
+        "node_modules/ignore": {
+            "version": "6.0.2",
+            "resolved": "https://registry.npmjs.org/ignore/-/ignore-6.0.2.tgz",
+            "integrity": "sha512-InwqeHHN2XpumIkMvpl/DCJVrAHgCsG5+cn1XlnLWGwtZBm8QJfSusItfrwx81CTp5agNZqpKU2J/ccC5nGT4A==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 4"
+            }
+        },
         "node_modules/import-fresh": {
             "version": "3.3.0",
             "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz",
@@ -2448,6 +2492,16 @@
             "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
             "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="
         },
+        "node_modules/ini": {
+            "version": "4.1.3",
+            "resolved": "https://registry.npmjs.org/ini/-/ini-4.1.3.tgz",
+            "integrity": "sha512-X7rqawQBvfdjS10YU1y1YVreA3SsLrW9dX2CewP2EbBJM4ypVNLDkO5y04gejPwKIY9lR+7r9gn3rFPt/kmWFg==",
+            "dev": true,
+            "license": "ISC",
+            "engines": {
+                "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
+            }
+        },
         "node_modules/ip-address": {
             "version": "9.0.5",
             "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-9.0.5.tgz",
@@ -2571,6 +2625,22 @@
                 "node": ">=8"
             }
         },
+        "node_modules/jackspeak": {
+            "version": "4.0.2",
+            "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-4.0.2.tgz",
+            "integrity": "sha512-bZsjR/iRjl1Nk1UkjGpAzLNfQtzuijhn2g+pbZb98HQ1Gk8vM9hfbxeMBP+M2/UUdwj0RqGG3mlvk2MsAqwvEw==",
+            "dev": true,
+            "license": "BlueOak-1.0.0",
+            "dependencies": {
+                "@isaacs/cliui": "^8.0.2"
+            },
+            "engines": {
+                "node": "20 || >=22"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/isaacs"
+            }
+        },
         "node_modules/jgexml": {
             "version": "0.4.4",
             "resolved": "https://registry.npmjs.org/jgexml/-/jgexml-0.4.4.tgz",
@@ -2622,6 +2692,13 @@
                 "node": ">= 4"
             }
         },
+        "node_modules/jsonc-parser": {
+            "version": "3.3.1",
+            "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
+            "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/jsonfile": {
             "version": "6.1.0",
             "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz",
@@ -2634,6 +2711,16 @@
                 "graceful-fs": "^4.1.6"
             }
         },
+        "node_modules/jsonpointer": {
+            "version": "5.0.1",
+            "resolved": "https://registry.npmjs.org/jsonpointer/-/jsonpointer-5.0.1.tgz",
+            "integrity": "sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=0.10.0"
+            }
+        },
         "node_modules/just-curry-it": {
             "version": "5.3.0",
             "resolved": "https://registry.npmjs.org/just-curry-it/-/just-curry-it-5.3.0.tgz",
@@ -2747,6 +2834,112 @@
                 "markdown-it": "bin/markdown-it.mjs"
             }
         },
+        "node_modules/markdownlint": {
+            "version": "0.35.0",
+            "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.35.0.tgz",
+            "integrity": "sha512-wgp8yesWjFBL7bycA3hxwHRdsZGJhjhyP1dSxKVKrza0EPFYtn+mHtkVy6dvP1kGSjovyG5B8yNP6Frj0UFUJg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "markdown-it": "14.1.0",
+                "markdownlint-micromark": "0.1.10"
+            },
+            "engines": {
+                "node": ">=18"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/DavidAnson"
+            }
+        },
+        "node_modules/markdownlint-cli": {
+            "version": "0.42.0",
+            "resolved": "https://registry.npmjs.org/markdownlint-cli/-/markdownlint-cli-0.42.0.tgz",
+            "integrity": "sha512-AjkzhhZa3TmEGi/CE2Wpmny69x1IrzqK2gPB0k8SmNMRgnSAJfyEO5FgZdWTHtJ6Nrdv5FWt5c4C5pkG6Dk30A==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "commander": "~12.1.0",
+                "get-stdin": "~9.0.0",
+                "glob": "~11.0.0",
+                "ignore": "~6.0.2",
+                "js-yaml": "^4.1.0",
+                "jsonc-parser": "~3.3.1",
+                "jsonpointer": "5.0.1",
+                "markdownlint": "~0.35.0",
+                "minimatch": "~10.0.1",
+                "run-con": "~1.3.2",
+                "smol-toml": "~1.3.0"
+            },
+            "bin": {
+                "markdownlint": "markdownlint.js"
+            },
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/markdownlint-cli/node_modules/brace-expansion": {
+            "version": "2.0.1",
+            "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz",
+            "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "balanced-match": "^1.0.0"
+            }
+        },
+        "node_modules/markdownlint-cli/node_modules/glob": {
+            "version": "11.0.0",
+            "resolved": "https://registry.npmjs.org/glob/-/glob-11.0.0.tgz",
+            "integrity": "sha512-9UiX/Bl6J2yaBbxKoEBRm4Cipxgok8kQYcOPEhScPwebu2I0HoQOuYdIO6S3hLuWoZgpDpwQZMzTFxgpkyT76g==",
+            "dev": true,
+            "license": "ISC",
+            "dependencies": {
+                "foreground-child": "^3.1.0",
+                "jackspeak": "^4.0.1",
+                "minimatch": "^10.0.0",
+                "minipass": "^7.1.2",
+                "package-json-from-dist": "^1.0.0",
+                "path-scurry": "^2.0.0"
+            },
+            "bin": {
+                "glob": "dist/esm/bin.mjs"
+            },
+            "engines": {
+                "node": "20 || >=22"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/isaacs"
+            }
+        },
+        "node_modules/markdownlint-cli/node_modules/minimatch": {
+            "version": "10.0.1",
+            "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.0.1.tgz",
+            "integrity": "sha512-ethXTt3SGGR+95gudmqJ1eNhRO7eGEGIgYA9vnPatK4/etz2MEVDno5GMCibdMTuBMyElzIlgxMna3K94XDIDQ==",
+            "dev": true,
+            "license": "ISC",
+            "dependencies": {
+                "brace-expansion": "^2.0.1"
+            },
+            "engines": {
+                "node": "20 || >=22"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/isaacs"
+            }
+        },
+        "node_modules/markdownlint-micromark": {
+            "version": "0.1.10",
+            "resolved": "https://registry.npmjs.org/markdownlint-micromark/-/markdownlint-micromark-0.1.10.tgz",
+            "integrity": "sha512-no5ZfdqAdWGxftCLlySHSgddEjyW4kui4z7amQcGsSKfYC5v/ou+8mIQVyg9KQMeEZLNtz9OPDTj7nnTnoR4FQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=18"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/DavidAnson"
+            }
+        },
         "node_modules/marked": {
             "version": "12.0.2",
             "resolved": "https://registry.npmjs.org/marked/-/marked-12.0.2.tgz",
@@ -2857,6 +3050,16 @@
                 "node": "*"
             }
         },
+        "node_modules/minimist": {
+            "version": "1.2.8",
+            "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
+            "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
+            "dev": true,
+            "license": "MIT",
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
         "node_modules/minipass": {
             "version": "7.1.2",
             "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.2.tgz",
@@ -3149,6 +3352,33 @@
                 "node": ">=8"
             }
         },
+        "node_modules/path-scurry": {
+            "version": "2.0.0",
+            "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.0.tgz",
+            "integrity": "sha512-ypGJsmGtdXUOeM5u93TyeIEfEhM6s+ljAhrk5vAvSx8uyY/02OvrZnA0YNGUrPXfpJMgI1ODd3nwz8Npx4O4cg==",
+            "dev": true,
+            "license": "BlueOak-1.0.0",
+            "dependencies": {
+                "lru-cache": "^11.0.0",
+                "minipass": "^7.1.2"
+            },
+            "engines": {
+                "node": "20 || >=22"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/isaacs"
+            }
+        },
+        "node_modules/path-scurry/node_modules/lru-cache": {
+            "version": "11.0.2",
+            "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.0.2.tgz",
+            "integrity": "sha512-123qHRfJBmo2jXDbo/a5YOQrJoHF/GNQTLzQ5+IdK5pWpceK17yRc6ozlWd25FxvGKQbIUs91fDFkXmDHTKcyA==",
+            "dev": true,
+            "license": "ISC",
+            "engines": {
+                "node": "20 || >=22"
+            }
+        },
         "node_modules/pathe": {
             "version": "1.1.2",
             "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.2.tgz",
@@ -3456,6 +3686,22 @@
                 "fsevents": "~2.3.2"
             }
         },
+        "node_modules/run-con": {
+            "version": "1.3.2",
+            "resolved": "https://registry.npmjs.org/run-con/-/run-con-1.3.2.tgz",
+            "integrity": "sha512-CcfE+mYiTcKEzg0IqS08+efdnH0oJ3zV0wSUFBNrMHMuxCtXvBCLzCJHatwuXDcu/RlhjTziTo/a1ruQik6/Yg==",
+            "dev": true,
+            "license": "(BSD-2-Clause OR MIT OR Apache-2.0)",
+            "dependencies": {
+                "deep-extend": "^0.6.0",
+                "ini": "~4.1.0",
+                "minimist": "^1.2.8",
+                "strip-json-comments": "~3.1.1"
+            },
+            "bin": {
+                "run-con": "cli.js"
+            }
+        },
         "node_modules/sade": {
             "version": "1.8.1",
             "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz",
@@ -3584,6 +3830,19 @@
                 "npm": ">= 3.0.0"
             }
         },
+        "node_modules/smol-toml": {
+            "version": "1.3.1",
+            "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.3.1.tgz",
+            "integrity": "sha512-tEYNll18pPKHroYSmLLrksq233j021G0giwW7P3D24jC54pQ5W5BXMsQ/Mvw1OJCmEYDgY+lrzT+3nNUtoNfXQ==",
+            "dev": true,
+            "license": "BSD-3-Clause",
+            "engines": {
+                "node": ">= 18"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/cyyynthia"
+            }
+        },
         "node_modules/socks": {
             "version": "2.8.3",
             "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.3.tgz",
@@ -3752,6 +4011,19 @@
                 "node": ">=8"
             }
         },
+        "node_modules/strip-json-comments": {
+            "version": "3.1.1",
+            "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz",
+            "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=8"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
         "node_modules/supports-color": {
             "version": "5.5.0",
             "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz",
@@ -5319,6 +5591,12 @@
             "resolved": "https://registry.npmjs.org/colors/-/colors-1.4.0.tgz",
             "integrity": "sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA=="
         },
+        "commander": {
+            "version": "12.1.0",
+            "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
+            "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
+            "dev": true
+        },
         "concat-map": {
             "version": "0.0.1",
             "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
@@ -5395,6 +5673,12 @@
             "integrity": "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==",
             "dev": true
         },
+        "deep-extend": {
+            "version": "0.6.0",
+            "resolved": "https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz",
+            "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==",
+            "dev": true
+        },
         "define-lazy-prop": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/define-lazy-prop/-/define-lazy-prop-2.0.0.tgz",
@@ -5716,6 +6000,12 @@
             "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
             "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="
         },
+        "get-stdin": {
+            "version": "9.0.0",
+            "resolved": "https://registry.npmjs.org/get-stdin/-/get-stdin-9.0.0.tgz",
+            "integrity": "sha512-dVKBjfWisLAicarI2Sf+JuBE/DghV4UzNAVe9yhEJuzeREd3JhOTE9cUaJTeSa77fsbQUK3pcOpJfM59+VKZaA==",
+            "dev": true
+        },
         "get-stream": {
             "version": "5.2.0",
             "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz",
@@ -5861,6 +6151,12 @@
             "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
             "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="
         },
+        "ignore": {
+            "version": "6.0.2",
+            "resolved": "https://registry.npmjs.org/ignore/-/ignore-6.0.2.tgz",
+            "integrity": "sha512-InwqeHHN2XpumIkMvpl/DCJVrAHgCsG5+cn1XlnLWGwtZBm8QJfSusItfrwx81CTp5agNZqpKU2J/ccC5nGT4A==",
+            "dev": true
+        },
         "import-fresh": {
             "version": "3.3.0",
             "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz",
@@ -5885,6 +6181,12 @@
             "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
             "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="
         },
+        "ini": {
+            "version": "4.1.3",
+            "resolved": "https://registry.npmjs.org/ini/-/ini-4.1.3.tgz",
+            "integrity": "sha512-X7rqawQBvfdjS10YU1y1YVreA3SsLrW9dX2CewP2EbBJM4ypVNLDkO5y04gejPwKIY9lR+7r9gn3rFPt/kmWFg==",
+            "dev": true
+        },
         "ip-address": {
             "version": "9.0.5",
             "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-9.0.5.tgz",
@@ -5969,6 +6271,15 @@
                 "istanbul-lib-report": "^3.0.0"
             }
         },
+        "jackspeak": {
+            "version": "4.0.2",
+            "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-4.0.2.tgz",
+            "integrity": "sha512-bZsjR/iRjl1Nk1UkjGpAzLNfQtzuijhn2g+pbZb98HQ1Gk8vM9hfbxeMBP+M2/UUdwj0RqGG3mlvk2MsAqwvEw==",
+            "dev": true,
+            "requires": {
+                "@isaacs/cliui": "^8.0.2"
+            }
+        },
         "jgexml": {
             "version": "0.4.4",
             "resolved": "https://registry.npmjs.org/jgexml/-/jgexml-0.4.4.tgz",
@@ -6004,6 +6315,12 @@
             "integrity": "sha512-q3PN0lbUdv0pmurkBNdJH3pfFvOTL/Zp0lquqpvcjfKzt6Y0j49EPHAmVHCAS4Ceq/Y+PejWTzyiVpoY71+D6g==",
             "dev": true
         },
+        "jsonc-parser": {
+            "version": "3.3.1",
+            "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
+            "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
+            "dev": true
+        },
         "jsonfile": {
             "version": "6.1.0",
             "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz",
@@ -6013,6 +6330,12 @@
                 "universalify": "^2.0.0"
             }
         },
+        "jsonpointer": {
+            "version": "5.0.1",
+            "resolved": "https://registry.npmjs.org/jsonpointer/-/jsonpointer-5.0.1.tgz",
+            "integrity": "sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ==",
+            "dev": true
+        },
         "just-curry-it": {
             "version": "5.3.0",
             "resolved": "https://registry.npmjs.org/just-curry-it/-/just-curry-it-5.3.0.tgz",
@@ -6101,6 +6424,75 @@
                 "uc.micro": "^2.1.0"
             }
         },
+        "markdownlint": {
+            "version": "0.35.0",
+            "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.35.0.tgz",
+            "integrity": "sha512-wgp8yesWjFBL7bycA3hxwHRdsZGJhjhyP1dSxKVKrza0EPFYtn+mHtkVy6dvP1kGSjovyG5B8yNP6Frj0UFUJg==",
+            "dev": true,
+            "requires": {
+                "markdown-it": "14.1.0",
+                "markdownlint-micromark": "0.1.10"
+            }
+        },
+        "markdownlint-cli": {
+            "version": "0.42.0",
+            "resolved": "https://registry.npmjs.org/markdownlint-cli/-/markdownlint-cli-0.42.0.tgz",
+            "integrity": "sha512-AjkzhhZa3TmEGi/CE2Wpmny69x1IrzqK2gPB0k8SmNMRgnSAJfyEO5FgZdWTHtJ6Nrdv5FWt5c4C5pkG6Dk30A==",
+            "dev": true,
+            "requires": {
+                "commander": "~12.1.0",
+                "get-stdin": "~9.0.0",
+                "glob": "~11.0.0",
+                "ignore": "~6.0.2",
+                "js-yaml": "^4.1.0",
+                "jsonc-parser": "~3.3.1",
+                "jsonpointer": "5.0.1",
+                "markdownlint": "~0.35.0",
+                "minimatch": "~10.0.1",
+                "run-con": "~1.3.2",
+                "smol-toml": "~1.3.0"
+            },
+            "dependencies": {
+                "brace-expansion": {
+                    "version": "2.0.1",
+                    "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz",
+                    "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==",
+                    "dev": true,
+                    "requires": {
+                        "balanced-match": "^1.0.0"
+                    }
+                },
+                "glob": {
+                    "version": "11.0.0",
+                    "resolved": "https://registry.npmjs.org/glob/-/glob-11.0.0.tgz",
+                    "integrity": "sha512-9UiX/Bl6J2yaBbxKoEBRm4Cipxgok8kQYcOPEhScPwebu2I0HoQOuYdIO6S3hLuWoZgpDpwQZMzTFxgpkyT76g==",
+                    "dev": true,
+                    "requires": {
+                        "foreground-child": "^3.1.0",
+                        "jackspeak": "^4.0.1",
+                        "minimatch": "^10.0.0",
+                        "minipass": "^7.1.2",
+                        "package-json-from-dist": "^1.0.0",
+                        "path-scurry": "^2.0.0"
+                    }
+                },
+                "minimatch": {
+                    "version": "10.0.1",
+                    "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.0.1.tgz",
+                    "integrity": "sha512-ethXTt3SGGR+95gudmqJ1eNhRO7eGEGIgYA9vnPatK4/etz2MEVDno5GMCibdMTuBMyElzIlgxMna3K94XDIDQ==",
+                    "dev": true,
+                    "requires": {
+                        "brace-expansion": "^2.0.1"
+                    }
+                }
+            }
+        },
+        "markdownlint-micromark": {
+            "version": "0.1.10",
+            "resolved": "https://registry.npmjs.org/markdownlint-micromark/-/markdownlint-micromark-0.1.10.tgz",
+            "integrity": "sha512-no5ZfdqAdWGxftCLlySHSgddEjyW4kui4z7amQcGsSKfYC5v/ou+8mIQVyg9KQMeEZLNtz9OPDTj7nnTnoR4FQ==",
+            "dev": true
+        },
         "marked": {
             "version": "12.0.2",
             "resolved": "https://registry.npmjs.org/marked/-/marked-12.0.2.tgz",
@@ -6184,6 +6576,12 @@
                 "brace-expansion": "^1.1.7"
             }
         },
+        "minimist": {
+            "version": "1.2.8",
+            "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
+            "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
+            "dev": true
+        },
         "minipass": {
             "version": "7.1.2",
             "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.2.tgz",
@@ -6373,6 +6771,24 @@
             "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
             "dev": true
         },
+        "path-scurry": {
+            "version": "2.0.0",
+            "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.0.tgz",
+            "integrity": "sha512-ypGJsmGtdXUOeM5u93TyeIEfEhM6s+ljAhrk5vAvSx8uyY/02OvrZnA0YNGUrPXfpJMgI1ODd3nwz8Npx4O4cg==",
+            "dev": true,
+            "requires": {
+                "lru-cache": "^11.0.0",
+                "minipass": "^7.1.2"
+            },
+            "dependencies": {
+                "lru-cache": {
+                    "version": "11.0.2",
+                    "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.0.2.tgz",
+                    "integrity": "sha512-123qHRfJBmo2jXDbo/a5YOQrJoHF/GNQTLzQ5+IdK5pWpceK17yRc6ozlWd25FxvGKQbIUs91fDFkXmDHTKcyA==",
+                    "dev": true
+                }
+            }
+        },
         "pathe": {
             "version": "1.1.2",
             "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.2.tgz",
@@ -6577,6 +6993,18 @@
                 "fsevents": "~2.3.2"
             }
         },
+        "run-con": {
+            "version": "1.3.2",
+            "resolved": "https://registry.npmjs.org/run-con/-/run-con-1.3.2.tgz",
+            "integrity": "sha512-CcfE+mYiTcKEzg0IqS08+efdnH0oJ3zV0wSUFBNrMHMuxCtXvBCLzCJHatwuXDcu/RlhjTziTo/a1ruQik6/Yg==",
+            "dev": true,
+            "requires": {
+                "deep-extend": "^0.6.0",
+                "ini": "~4.1.0",
+                "minimist": "^1.2.8",
+                "strip-json-comments": "~3.1.1"
+            }
+        },
         "sade": {
             "version": "1.8.1",
             "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz",
@@ -6665,6 +7093,12 @@
             "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz",
             "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg=="
         },
+        "smol-toml": {
+            "version": "1.3.1",
+            "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.3.1.tgz",
+            "integrity": "sha512-tEYNll18pPKHroYSmLLrksq233j021G0giwW7P3D24jC54pQ5W5BXMsQ/Mvw1OJCmEYDgY+lrzT+3nNUtoNfXQ==",
+            "dev": true
+        },
         "socks": {
             "version": "2.8.3",
             "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.3.tgz",
@@ -6782,6 +7216,12 @@
                 "ansi-regex": "^5.0.1"
             }
         },
+        "strip-json-comments": {
+            "version": "3.1.1",
+            "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz",
+            "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==",
+            "dev": true
+        },
         "supports-color": {
             "version": "5.5.0",
             "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz",
@@ -7176,4 +7616,4 @@
             "integrity": "sha512-XBx9AXhXktjUqnepgTiE5flcKIYWi/rme0Eaj+5Y0lftuGBq+jyRu/md4WnuxqgP1ubdpNCsYEYPxrzVHD8d6g=="
         }
     }
-}
\ No newline at end of file
+}
diff --git a/package.json b/package.json
index 3d46428..f8d5025 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,8 @@
     "description": "Arazzo Specification",
     "scripts": {
         "build": "bash ./scripts/md2html/build.sh",
-        "test": "c8 --100 vitest --watch=false && bash scripts/schema-test-coverage.sh"
+        "test": "c8 --100 vitest --watch=false && bash scripts/schema-test-coverage.sh",
+        "format-markdown": "bash ./scripts/format-markdown.sh versions/1.0.[^0].md versions/1.[1-9].*.md versions/2.*.md"
     },
     "repository": {
         "type": "git",
@@ -41,6 +42,7 @@
         "yaml": "2.4.2",
         "@hyperjump/json-schema": "^1.9.9",
         "c8": "^10.1.2",
-        "vitest": "^2.1.3"
+        "vitest": "^2.1.3",
+        "markdownlint-cli": "^0.42.0"
     }
 }
diff --git a/scripts/format-markdown.sh b/scripts/format-markdown.sh
new file mode 100644
index 0000000..c0f5246
--- /dev/null
+++ b/scripts/format-markdown.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+SRCDIR="$(dirname "${BASH_SOURCE[0]}")" # check on Windows
+
+for filename in $*; do
+  # check if the $filename exists and if it's writeable
+  if [ ! -w $filename ]; then
+  echo "No matching file found: $filename"
+  continue;
+  fi
+  # mostly to format code blocks with examples, unfortunately messes up bullet lists and tables
+  npx prettier --write --single-quote $filename
+
+  # repair the tables: remove superfluos spaces and dashes that make diffing revisions harder
+  # and sed -i is not portable, so we need to use a temporary file
+  sed -E -e "s/  +\|/ |/g" -e "s/\|  +/| /g" -e "s/-----+/----/g" $filename > $filename.tmp && mv $filename.tmp $filename
+
+  # repair the bullet lists and various other markdown formatting issues
+  npx --yes markdownlint-cli --fix --config $SRCDIR/../.markdownlint.yaml $filename
+done