radius-markdown-lint

# 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: Check for hard-wrapped prose (manual) The tools **cannot** catch hard-wrapped prose. The line-length rule (MD013) is intentionally disabled, and markdownlint has no rule for the inverse problem — a paragraph split across several lines. So this convention is enforced by eye, not by tooling. The repository convention (see `.github/instructions/markdown.instructions.md`) is: **write each paragraph as a single long line.** Do not insert manual line breaks inside a paragraph, a list item's text, or a blockquote. To check, scan each file you changed for a run of two or more consecutive non-blank prose lines that are not separated by a blank line, for example: ```markdown <!-- Wrong: hard-wrapped --> This paragraph has been split across two lines, which creates noisy diffs. <!-- Right: one line per paragraph --> This paragraph is a single long line, which reflows cleanly in editors and produces clean diffs. ``` When you find one, join the lines into a single line. This applies to paragraphs, list item text, and blockquote (`>`) content. It does **not** apply to fenced code blocks, tables, or `<!-- ... -->` comment blocks, which may span multiple lines. ### Step 5: 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 6: 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'` |