// markdown · diagnostics · validation

MeDiVa

Catch broken Markdown before it ships — or before your agent chokes on it.

Write a contract once. mediva checks every generated document against it and points at the exact tag, rule, and line that failed.

Read the docs →GitHubnpm install -D mediva

// what it catches

Structure that must hold

Require the sections, ordering, and shape a document needs — and reject the ones it doesn't. Not regex: mediva reads the Markdown tree.

◈

Proof, not prose

An agent can write "Done ✅". A mediva contract makes it show the section, the checked box, the table column — or fail.

⌁

Exact, machine-readable findings

Every failure names the tag, the rule, and the line, with a stable code. Gate it in CI or read it from the API.

// the benchmark

Models ship broken Markdown. Constantly.

Generated docs drift — missing sections, unchecked boxes, malformed tables. mediva catches it, and the same contract tells the agent how to repair it.

Model A21% → 0.8%

Model B14% → 0.5%

Model C31% → 1.2%

Model D44% → 2%

raw defect rate (✕) vs. after-repair (✓) · illustrative

// drop it into your stack

Three lines.
Any stack.

A CI gate, a CLI call, a Node import, or a step in your agent pipeline — same contract, same findings.

# .github/workflows/mediva.yml
- uses: actions/checkout@v4
- uses: jamespacileo/mediva@v0.2.0

// run it

Point it at a glob.
Get the truth.

One command, an exit code, and exact findings. A drop-in CI gate or a step in your agent pipeline.

$ mediva check ./docs/**/*.md --schema docs.mdv.md

✕ readme.md:1  [missing-section] The "Installation" section is missing.
▲ guide.md:14  [too-few-words] The "Summary" section is too short (4 words).

1 error, 1 warning

// the template your agents fill in

Old Markdown asks for prose.
MeDiVa asks for proof.

a plain template — the agent writes "Done ✅"

## Summary
TODO

## Checklist
- [x] Done ✅

a mediva contract — it demands the proof

<!-- mdv: block required minWords=20 noPlaceholder -->
## Summary
<!-- mdv: endblock -->

<!-- mdv: taskList required allChecked exactLabels -->
## Checklist
- [ ] Tests added or updated
- [ ] Docs updated
<!-- mdv: endtaskList -->

// the part nobody shows you

See what your agent
actually reads.

Raw output looks done. Run the contract and the gaps surface — by tag, rule, and line.

## Summary
TODO

## Checklist
- [x] Done ✅

Try it on your own Markdown.

Write the shape once. Trust every output.

Quickstart →Browse the reference