mdsmith check

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

Flags

Flag	Default	Description
-c, --config	auto	Override config path (auto-discovers)
-f, --format	text	text, json, or sarif
--max-input-size	2MB	Max file size (e.g. 2MB, 0=none)
--no-color	false	Plain output
--follow-symlinks	config	Follow symlinks; tri-state — see below
--no-gitignore	false	Skip gitignore filtering
-q, --quiet	false	Suppress non-error output
-v, --verbose	false	Show config, files, and rules
--explain	false	Attach per-leaf rule provenance

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

Code	Meaning
0	No lint issues found
1	Lint issues found
2	Runtime or configuration error

See also

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