Add markdown instructions aligned with markdownlint config (#12093)

## Description

Adds `.github/instructions/markdown.instructions.md` describing Markdown
formatting best practices based on markdownlint rules.

The guidance is aligned with the markdownlint configuration used in
`radius-project/wellknown`:

- MD024 (duplicate heading content), MD036 (emphasis as heading), and
MD041 (first-line heading) are noted as disabled.
- MD013 (line length) is not enforced.
- Configured options reflected: MD004 (dash), MD029 (one_or_ordered),
MD033 (only `<br>` and `<pre>` allowed), and MD046 (fenced).

## Type of change

- This pull request adds or changes features of Radius and has an
approved issue (issue link required).
- This pull request is a minor refactor, code cleanup, test improvement,
or documentation update and doesn't change any functionality.

---------

Signed-off-by: Brooke Hamilton <45323234+brooke-hamilton@users.noreply.github.com>

Author: brooke-hamilton

.github/instructions/markdown.instructions.md

@@ -0,0 +1,25 @@
+---
+description: 'Conventions for authoring Markdown in this repository'
+applyTo: '**/*.md'
+---
+
+# Markdown Guidelines
+
+Formatting rules for Markdown are enforced by tooling. This file covers only the conventions the linters cannot check and points to the source of truth for everything else.
+
+## Source of truth
+
+Do not restate or duplicate lint rules here — change the configuration instead, otherwise this file will drift from what is actually enforced.
+
+- **Rules:** `markdownlint-cli2`, configured by [`.github/linters/.markdownlint-cli2.yaml`](../linters/.markdownlint-cli2.yaml), which extends [`.github/linters/.markdownlint.yml`](../linters/.markdownlint.yml).
+- **Tables:** formatted by `markdown-table-formatter`.
+
+Both tools are installed as dev dependencies in the root `package.json`. See the `markdown-lint` skill for how to run them.
+
+## Conventions not enforced by tooling
+
+- **Do not hard-wrap prose.** Write each paragraph as a single long line. The line-length rule (MD013) is intentionally disabled; manual line breaks create noisy diffs and break reflowing in editors. This applies to all prose — paragraphs, list item text, blockquote content, and image/link alt text. Code blocks and tables are excluded.
+
+## Before committing
+
+Run the Markdown linters (see the `markdown-lint` skill) on the files you changed and fix any reported issues.

.github/linters/.markdownlint-cli2.yaml

@@ -0,0 +1,11 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/main/schema/markdownlint-cli2-config-schema.json
+---
+config:
+  extends: ./.markdownlint.yml
+gitignore: true
+ignores:
+  - .git
+  - "**/node_modules/**"
+  - .copilot-tracking/**
+  - venv/**
+  - .venv/**

.github/linters/.markdownlint.yml

@@ -0,0 +1,44 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/DavidAnson/markdownlint/refs/heads/main/schema/markdownlint-config-schema-strict.json
+---
+# Markdownlint YAML configuration
+# Default source: https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
+
+# Default state for all rules
+default: true
+
+# Path to configuration file to extend
+# extends: null
+
+# MD004/ul-style - Unordered list style - https://github.com/DavidAnson/markdownlint/blob/main/doc/md004.md
+MD004:
+  style: dash
+
+# MD013/line-length - Line length - https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
+MD013: false
+
+# MD024/no-duplicate-heading - Multiple headings with the same content - https://github.com/DavidAnson/markdownlint/blob/main/doc/md024.md
+MD024: false
+
+# MD025/single-title - Single title - https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md
+MD025:
+  front_matter_title: ""
+
+# MD029/ol-prefix - Ordered list item prefix - https://github.com/DavidAnson/markdownlint/blob/main/doc/md029.md
+MD029:
+  style: one_or_ordered
+
+# MD033/no-inline-html - Inline HTML - https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
+MD033:
+  # Allowed elements
+  allowed_elements: [br, pre]
+
+# MD036/no-emphasis-as-heading - Emphasis used instead of a heading -  https://github.com/DavidAnson/markdownlint/blob/main/doc/md036.md
+MD036: false
+
+# MD041/first-line-heading/first-line-h1 - First line in file should be a top level heading - https://github.com/DavidAnson/markdownlint/blob/main/doc/md041.md
+MD041: false
+
+# MD046/code-block-style - Code block style - https://github.com/DavidAnson/markdownlint/blob/main/doc/md046.md
+MD046:
+  # Block style
+  style: fenced

.github/skills/markdown-lint/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: markdown-lint
+description: 'Lint and format Markdown files using markdownlint-cli2 and markdown-table-formatter. Use when checking or fixing Markdown formatting, table alignment, or markdownlint rule violations after editing .md files.'
+argument-hint: 'Optional: the path(s) or glob of Markdown files to lint — or leave blank to lint files you changed'
+user-invocable: true
+---
+
+# Lint Markdown
+
+Check and fix Markdown formatting using the repository's two Markdown tools, driven by `pnpm`.
+
+## Overview
+
+Markdown quality is enforced by two tools, both installed as dev dependencies in the root `package.json`:
+
+- **`markdownlint-cli2`** — applies the markdownlint rules in [`.github/linters/.markdownlint-cli2.yaml`](../../linters/.markdownlint-cli2.yaml), which extends [`.github/linters/.markdownlint.yml`](../../linters/.markdownlint.yml). It honors the `ignores`/`gitignore` settings in that config (so `node_modules`, `.git`, etc. are skipped automatically).
+- **`markdown-table-formatter`** — normalizes Markdown table alignment and padding. It has no config file and only accepts CLI flags (`--check`, `--columnpadding`, `--verbose`). It does **not** read `.gitignore`, so scope it to specific files or directories rather than the whole tree.
+
+## Prerequisites
+
+1. **Node.js + pnpm**: pnpm is pinned via the `packageManager` field in `package.json`. If pnpm is missing, run `corepack enable pnpm`.
+2. **Install dependencies**: run `pnpm install --frozen-lockfile` from the repository root so the tool binaries are available.
+
+## Procedure
+
+### Step 1: Determine the scope
+
+Prefer linting only the files you changed instead of the entire repository.
+
+- For changed files: `git diff --name-only --diff-filter=d HEAD '*.md'`
+- For a directory: use a glob such as `"docs/**/*.md"`.
+- Avoid passing `"./**/*.md"` to `markdown-table-formatter` — it will traverse `node_modules` because it does not respect `.gitignore`.
+
+### Step 2: Check (read-only)
+
+Run both tools in check mode. Replace `<glob-or-paths>` with the scope from Step 1.
+
+```bash
+# Check table formatting (exits non-zero if any table needs reformatting)
+pnpm exec markdown-table-formatter "<glob-or-paths>" --check
+
+# Check markdownlint rules
+pnpm exec markdownlint-cli2 "<glob-or-paths>" --config "./.github/linters/.markdownlint-cli2.yaml"
+```
+
+### Step 3: Fix
+
+Apply automatic fixes, then re-run the checks in Step 2 to confirm a clean result.
+
+```bash
+# Reformat tables in place
+pnpm exec markdown-table-formatter "<glob-or-paths>"
+
+# Auto-fix markdownlint violations where possible
+pnpm exec markdownlint-cli2 "<glob-or-paths>" --config "./.github/linters/.markdownlint-cli2.yaml" --fix
+```
+
+### Step 4: Resolve remaining issues
+
+Not every markdownlint rule is auto-fixable. For violations that remain after Step 3, edit the Markdown manually following the rule messages. Do not hard-wrap prose to satisfy line length — the MD013 line-length rule is intentionally disabled (see the Markdown authoring guidelines in `.github/instructions/markdown.instructions.md`).
+
+### Step 5: Report result
+
+Summarize what was checked, what was fixed automatically, and any violations that require manual attention.
+
+## Quick Reference
+
+| Goal                        | Command                                                                                           |
+|-----------------------------|---------------------------------------------------------------------------------------------------|
+| Check table formatting      | `pnpm exec markdown-table-formatter "<glob>" --check`                                             |
+| Fix table formatting        | `pnpm exec markdown-table-formatter "<glob>"`                                                     |
+| Check markdownlint rules    | `pnpm exec markdownlint-cli2 "<glob>" --config "./.github/linters/.markdownlint-cli2.yaml"`       |
+| Fix markdownlint rules      | `pnpm exec markdownlint-cli2 "<glob>" --config "./.github/linters/.markdownlint-cli2.yaml" --fix` |
+| List changed Markdown files | `git diff --name-only --diff-filter=d HEAD '*.md'`                                                |

.vscode/extensions.json

@@ -1,7 +1,8 @@
 {
-  "recommendations": [
-    "ms-azuretools.vscode-bicep",
-    "golang.go",
-    "GitHub.vscode-pull-request-github"
-  ]
+    "recommendations": [
+        "ms-azuretools.vscode-bicep",
+        "golang.go",
+        "GitHub.vscode-pull-request-github",
+        "DavidAnson.vscode-markdownlint"
+    ]
 }

.vscode/settings.json

@@ -9,6 +9,14 @@
         "*.yaml": "yaml",
         "*.yml": "yaml"
     },
+    "files.trimTrailingWhitespace": true,
+    "files.insertFinalNewline": true,
+    "[markdown]": {
+        "editor.defaultFormatter": "DavidAnson.vscode-markdownlint",
+        "editor.formatOnSave": true,
+        "editor.formatOnPaste": true
+    },
+    "markdownlint.configFile": "./.github/linters/.markdownlint.yml",
     "terminal.integrated.env.linux": {
         "RADIUS_DEV_ROOT": "${workspaceFolder}/debug_files"
     },

package.json

@@ -2,6 +2,8 @@
   "private": true,
   "packageManager": "pnpm@11.1.1",
   "devDependencies": {
+    "markdown-table-formatter": "1.7.0",
+    "markdownlint-cli2": "0.22.1",
     "prettier": "3.8.4"
   }
 }