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, which extends .github/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.

# 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.

# 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:

<!-- 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