Add markdown linting tools and scripts

- Create package.json to manage markdownlint-cli2 as a dev dependency.
- Add PowerShell script for linting Markdown files with options for fixing issues.
- Update shell script to prefer locally installed markdownlint-cli2 or fallback to npx.

.github/workflows/ci.yml

@@ -14,6 +14,15 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install pinned linter
+        run: npm ci
+
       - name: Run markdownlint
         run: bash scripts/lint-markdown.sh
 

package.json

@@ -0,0 +1,12 @@
+{
+  "name": "echohub",
+  "private": true,
+  "description": "Repo tooling — markdown linting. Not an npm package.",
+  "scripts": {
+    "lint:md": "markdownlint-cli2",
+    "lint:md:fix": "markdownlint-cli2 --fix"
+  },
+  "devDependencies": {
+    "markdownlint-cli2": "^0.23.0"
+  }
+}

scripts/lint-markdown.ps1

@@ -0,0 +1,61 @@
+# EchoHub - Markdown Lint
+#
+# Runs markdownlint-cli2 over the repo. Rules, globs, and ignores all live in
+# .markdownlint-cli2.jsonc; the linter version is pinned in package.json.
+#
+# Usage:
+#   .\scripts\lint-markdown.ps1            # lint-only, exits non-zero on violations
+#   .\scripts\lint-markdown.ps1 -Fix       # auto-fix what markdownlint can
+#
+# Requires: Node + npx on PATH. Prefers the locally installed linter
+# (`npm install` once); otherwise npx fetches the same pinned version.
+
+param(
+    [switch]$Fix
+)
+
+$ErrorActionPreference = "Stop"
+
+if (-not (Get-Command npx -ErrorAction SilentlyContinue)) {
+    Write-Host "  ERROR: npx not found on PATH. Install Node.js (https://nodejs.org) and retry." -ForegroundColor Red
+    exit 1
+}
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$RootDir   = Split-Path -Parent $ScriptDir
+
+Push-Location $RootDir
+try {
+    # Local install is version-pinned via package.json/package-lock.json; the
+    # npx fallback pins the same version so CI and local can never drift.
+    if (Test-Path "node_modules/.bin/markdownlint-cli2") {
+        $npxArgs = @('--no-install', 'markdownlint-cli2')
+    } else {
+        $npxArgs = @('--yes', '[email protected]')
+    }
+
+    if ($Fix) {
+        Write-Host "  Auto-fix mode (--fix): markdownlint will rewrite files in place." -ForegroundColor Yellow
+        $npxArgs += '--fix'
+    }
+
+    Write-Host "  > npx $($npxArgs -join ' ')" -ForegroundColor Gray
+    & npx @npxArgs
+    $exit = $LASTEXITCODE
+
+    if ($exit -eq 0) {
+        Write-Host "  Markdown lint clean." -ForegroundColor Green
+    } elseif ($Fix) {
+        Write-Host ""
+        Write-Host "  Some issues could not be auto-fixed. Review the output above and fix manually." -ForegroundColor Yellow
+    } else {
+        Write-Host ""
+        Write-Host "  Markdown lint failed. Re-run with -Fix to auto-correct the fixable rules:" -ForegroundColor Red
+        Write-Host "    .\scripts\lint-markdown.ps1 -Fix" -ForegroundColor Yellow
+    }
+
+    exit $exit
+}
+finally {
+    Pop-Location
+}

scripts/lint-markdown.sh

@@ -2,6 +2,8 @@
 #
 # Lint all Markdown files in the repository.
 # Config, globs, and ignores are defined in .markdownlint-cli2.jsonc.
+# The linter version is pinned in package.json — run `npm install` once,
+# or just use `npm run lint:md` / `npm run lint:md:fix` directly.
 #
 # Usage:
 #   ./scripts/lint-markdown.sh          # check
@@ -12,11 +14,12 @@ set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$REPO_ROOT"
 
-# Resolve markdownlint-cli2 binary
+# Prefer the locally installed (version-pinned) linter; fall back to a one-off
-if command -v markdownlint-cli2 &>/dev/null; then
+# npx install of the same version pinned in package.json.
-    LINT_CMD="markdownlint-cli2"
+if [ -x "node_modules/.bin/markdownlint-cli2" ]; then
+    LINT_CMD="npx --no-install markdownlint-cli2"
 else
-    LINT_CMD="npx --yes markdownlint-cli2"
+    LINT_CMD="npx --yes markdownlint-cli2@0.23.0"
 fi
 
 echo "Linting Markdown files..."