# Radius Markdown Lint

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

- Skill: `radius-project/radius-markdown-lint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add radius-project/radius-markdown-lint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/radius-project/radius-markdown-lint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: radius-project (https://skillmd.com/u/radius-project)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/radius-project/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'`                                                |