mdsmith check

Lint Markdown files for style issues.

Walks the workspace, parses each file once, runs every configured rule, and prints diagnostics — without writing anything back. Also covers structure and cross-file integrity, not only line-level style.

mdsmith check [flags] [files...]

Files can be paths, directories (walked recursively for *.md and *.markdown), or glob patterns. Pass - to read from stdin. With no file arguments, files are discovered from .mdsmith.yml files: patterns (default: **/*.md, **/*.markdown).

Only Markdown files are linted. A non-Markdown path (such as .gitattributes) is skipped whether the walk reaches it or you name it explicitly. Naming one explicitly prints a skipping …: not a Markdown file warning on stderr, so the skip is never a silent no-op; --quiet and the json/sarif formats suppress it.

# Flags

--follow-symlinks is tri-state. Omitted defers to the config key (default: skip). --follow-symlinks or =true opts in for this run. =false forces skip even when config opts in.

Symlinks resolving to directories, FIFOs, devices, or sockets are always skipped.

--explain adds an explanation field to each JSON diag (or a └─ trailer in text output) naming the rule and the winning source for each leaf setting:

"explanation": {"rule": "line-length", "leaves": [
  {"path": "enabled", "value": true, "source": "default"},
  {"path": "settings.max", "value": 30, "source": "kinds.short"}
]}

# Examples

mdsmith check docs/                  # lint a directory
mdsmith check -f json docs/          # JSON output
mdsmith check -f sarif docs/         # SARIF 2.1.0 output
mdsmith check --explain README.md    # provenance trailer
echo "# Hi" | mdsmith check -        # lint stdin

# GitHub Code Scanning

-f sarif emits a SARIF 2.1.0 document that GitHub’s Code Scanning dashboard ingests directly. Upload with github/codeql-action/upload-sarif :

- name: Run mdsmith
  run: mdsmith check -f sarif . 2> report.sarif || true
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: report.sarif
    category: mdsmith

Each fired rule links back to its mdsmith.dev doc page via helpUri in the SARIF driver.rules array.

# Pre-commit

# lefthook.yml
pre-commit:
  commands:
    mdsmith:
      glob: "*.{md,markdown}"
      run: mdsmith check {staged_files}

# Exit codes

# See also

• mdsmith fix — auto-fix the issues check reports
• Output and JSON schema