From 9792d1808022673eff93f9dceb62c390afd5c129 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Amaury=20Lev=C3=A9?= <amauryleve@microsoft.com>
Date: Fri, 17 Apr 2026 20:17:33 +0200
Subject: [PATCH] Add markdownlint analysis for local dev and CI (#534)

* Add markdownlint analysis for local dev and CI

- Add .markdownlint.jsonc with rule configuration
- Add .markdownlint-cli2.jsonc with ignore patterns
- Add package.json with markdownlint-cli2 and lint scripts
- Add GitHub Actions workflow running on PRs touching *.md files
- Add VS Code extension recommendation for vscode-markdownlint

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Address review comments: use markdownlint-cli2-action, merge configs, lint only changed files

- Replace manual Node.js + npm setup with DavidAnson/markdownlint-cli2-action (pinned to SHA)
- Use tj-actions/changed-files to lint only PR-changed markdown files
- Merge .markdownlint.jsonc into .markdownlint-cli2.jsonc (single config file)
- Remove package.json and package-lock.json (no longer needed)

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 .github/workflows/markdownlint.yml | 39 ++++++++++++++++++++++++++++++
 .markdownlint-cli2.jsonc           | 30 +++++++++++++++++++++++
 .vscode/extensions.json            |  5 ++++
 3 files changed, 74 insertions(+)
 create mode 100644 .github/workflows/markdownlint.yml
 create mode 100644 .markdownlint-cli2.jsonc
 create mode 100644 .vscode/extensions.json

diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml
new file mode 100644
index 00000000..c3fb9458
--- /dev/null
+++ b/.github/workflows/markdownlint.yml
@@ -0,0 +1,39 @@
+name: markdownlint
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+      - ".markdownlint-cli2.jsonc"
+      - ".github/workflows/markdownlint.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Get changed Markdown files
+        uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v47
+        id: changed-files
+        with:
+          files: "**/*.md"
+          separator: ","
+
+      - name: Run markdownlint
+        if: steps.changed-files.outputs.any_changed == 'true'
+        uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9 # v23
+        with:
+          globs: ${{ steps.changed-files.outputs.all_changed_files }}
+          separator: ","
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
new file mode 100644
index 00000000..37f3a5cf
--- /dev/null
+++ b/.markdownlint-cli2.jsonc
@@ -0,0 +1,30 @@
+{
+  // Glob patterns to ignore
+  "ignores": [
+    "node_modules/**",
+    "artifacts/**"
+  ],
+
+  // Inline markdownlint configuration (merged from .markdownlint.jsonc)
+  "config": {
+    // Default: enable all rules
+    "default": true,
+
+    // MD013 - Line length: disable because skill files and docs routinely have long lines
+    "MD013": false,
+
+    // MD024 - Multiple headings with the same content: allow siblings with same text
+    "MD024": {
+      "siblings_only": true
+    },
+
+    // MD033 - Inline HTML: allow specific elements commonly used in docs
+    "MD033": {
+      "allowed_elements": ["br", "details", "summary", "img", "a", "sub", "sup"]
+    },
+
+    // MD041 - First line in a file should be a top-level heading:
+    // Disable because SKILL.md files start with YAML frontmatter
+    "MD041": false
+  }
+}
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 00000000..c3d9e054
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "DavidAnson.vscode-markdownlint"
+  ]
+}