ci: add markdown lint job and gate it in lint-and-test

Add a dedicated markdown job (markdownlint, org-standard config) and include it in the lint-and-test aggregator's needs so markdown is covered by the required check; existing violations fixed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: DaveSkender

.github/workflows/ci.yml

@@ -30,9 +30,17 @@ jobs:
       run: |
         pylint $(git ls-files '*.py')
 
+  markdown:
+    runs-on: ubuntu-slim
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v6
+      - name: Lint markdown
+        uses: DavidAnson/markdownlint-cli2-action@v23
+
   lint-and-test:
     runs-on: ubuntu-slim
-    needs: [build]
+    needs: [build, markdown]
     if: always()
     steps:
       - name: Verify required jobs succeeded

.markdownlint-cli2.jsonc

@@ -0,0 +1,22 @@
+{
+  "globs": ["**/*.md"],
+  "gitignore": true,
+  "ignores": ["node_modules/**"],
+  "config": {
+    "default": true,
+    "MD003": { "style": "atx" },
+    "MD004": { "style": "dash" },
+    "MD007": { "indent": 2 },
+    "MD013": false, // allow long lines
+    "MD024": { "siblings_only": true },
+    "MD028": false, // allow separation between quote blocks
+    "MD033": {
+      "allowed_elements": ["details", "summary", "br", "sub", "sup", "kbd", "abbr", "a", "img"]
+    },
+    "MD041": false,
+    "MD046": { "style": "fenced" },
+    "MD048": { "style": "backtick" },
+    "MD055": { "style": "leading_and_trailing" },
+    "MD060": { "style": "compact", "aligned_delimiter": false }
+  }
+}