visimark check fails CI the moment a number and its formula disagree.
This is the one that matters — Author and Adopt exist to get you
here. VisiMark catches:
Not just a spreadsheet for Markdown — a build tool, an agent harness, a human error
verifier, executable documentation and a safety net for stale artifacts.
1. Build tool — test-suite sharding
CI needs to split a test suite across parallel runners so no single shard drags. Most
teams keep that split in a hand-maintained matrix that quietly drifts from the suite's
real shape. Here the sharding policy is the document, and visimark eval is
the thing CI itself reads to build the matrix.
An autonomous coding agent needs a spending cap it can't talk itself out of. Here the
cap and the running spend live in a document a harness checks before the next tool call
is allowed to fire — the enforcement point sits outside the agent entirely.
A structural calc gets retyped by hand between engineer, permit office and contractor,
and every retyping risks a transposed digit — a failure mode with no compile
error. This calculation sheet is built to catch exactly that before anyone builds the
deck.
Pricing pages, sales decks and billing configs usually restate the same numbers
independently until one of them lags behind a tier change. Here the pricing policy's
prose and the exact values the billing engine reads at deploy time are the same file.
5. Safety net for stale artifacts — an onboarding
dashboard
A funnel chart pasted into a quarterly slide looks current forever, even after the
numbers behind it move. Here the chart is a generated artifact of the document, and
check refuses to let it disagree with the table beside it.
See VisiMark in action, from the first formula to a red build.
VisiMark turns numbers in Markdown from claims into auditable derivations.
Ten ways that shows up, from the first formula to a red build.
Markdown that computes itself
Keep the document. Add the mechanics.
VisiMark brings formulas, derived values, totals and verification to Markdown —
without turning your document into a proprietary spreadsheet. The table below is
ordinary GFM. The vmark block next to it is the only new thing: one rule
per column, one aggregate, one anchor. Source on the left, what a reader actually sees
on the right.
figures.md
Rendered preview
→ Still Markdown. Now verifiable.
A document can look right and still be wrong
Someone changes an input. The document still renders normally. The numbers still look
plausible. But the calculation is now wrong. VisiMark can tell you.
Below is a real invoice, live: someone raised on-call hours from 12 to 20 and nothing
else changed. Read it the way a reviewer would.
invoice.md
Rendered preview
Nothing looks wrong. That's the point — on-call hours went from 12 to 20, and
every figure derived from it stayed behind.
$ visimark check invoice.md
invoice.md
STALE lines.Net · On-call support 3120.00 ≠ 5200.00 Qty * RateSTALE lines.VAT · On-call support 717.60 ≠ 1196.00 Net * vatSTALE lines.Gross · On-call support 3837.60 ≠ 6396.00 Net + VATSTALE lines.net_total 23300.00 ≠ 25380.00 SUM(Net)STALE lines.vat_total 5359.00 ≠ 5837.40 SUM(VAT)STALE lines.gross_total 28659.00 ≠ 31217.40 SUM(Gross)… 15 more, from an unparseable date and a broken cross-sheet reference elsewhere in the file
26 problems (21 stale, 5 errors)
$ echo $?
1
Don't rewrite an existing table by hand. VisiMark can inspect the values and infer
rules that explain how they were calculated.
quote.md below is ordinary Markdown — someone typed every cell by
hand, and the numbers agree only because they were careful. Run infer and
watch the rule appear.
When the numbers admit more than one explanation, infer says so instead of
guessing: a rule that fits every row but one is reported as a near-miss and never
written, even with --write.
Change one input, follow every consequence
Change an input once. VisiMark follows its dependencies and recalculates the values
that depend on it.
invoice.md
| Item | Qty | Rate | Net | VAT | Gross |
|-----------------|----:|-------:|--------:|--------:|--------:|
| On-call support | 12 | 260.00 | 3120.00 | 717.60 | 3837.60 |
```vmark #lines
Net = Qty * Rate
VAT = Net * vat
Gross = Net + VAT
Amount = SUM(lines.Gross)
```
Due on delivery: **3837.60**<!--vmark=lines.Amount--> PLN.
| Item | Qty | Rate | Net | VAT | Gross |
|-----------------|----:|-------:|--------:|--------:|--------:|
| On-call support | 20 | 260.00 | 5200.00 | 1196.00 | 6396.00 |
```vmark #lines
Net = Qty * Rate
VAT = Net * 0.23
Gross = Net + VAT
Amount = SUM(lines.Gross)
```
Due on delivery: **6396.00**<!--vmark=lines.Amount--> PLN.
What it recalculates
graph TD
Qty --> Net
Rate --> Net
Net --> VAT
Net --> Gross
Gross --> Amount["lines.Amount"]
→ One source of truth. Predictable downstream changes.
Review calculations like code
Calculated values live in your Markdown. Changes remain normal text changes. Review
them in Git, in a pull request, or in a code review.
fmt locates each value it owns by byte position and splices the original
text — it never round-trips through a Markdown printer, which would reformat every
paragraph and list in the file. Hypothetically, if it did:
→ The document stays a first-class version-controlled artifact.
Green means verified
A clean document is not necessarily a verified document. VisiMark also checks whether
your tables are actually covered by rules.
A checker that only compares numbers to rules would call a table with no rules
clean — the most misleading answer it could give. check
reports it as a problem in its own right:
$ visimark check quote.md
quote.md
COVERAGE a table with no `vmark` rules — nothing in this document is checked
run `visimark infer` to derive them, or mark it <!--vmark:no-formulas-->
1 problem (0 stale, 1 error)
$ visimark check quote.md
✓ quote.md — every value agrees
$ echo $?
0
→ The checkmark is a claim: these numbers were actually checked.
Put verification in CI
Don't just check the document. Check every change. Every pull request can verify that
calculated values still agree with their rules before the change merges.
graph LR
PR["PR #184"] --> Check["check"]
Check --> Pass[PASS] --> Merge
Check --> Fail[FAIL] --> Fix["fmt"]
class Pass pass
class Fail fail
classDef pass fill:#eafaf0,stroke:#1a7f37,color:#1a7f37,font-weight:bold;
classDef fail fill:#fdecea,stroke:#c0392b,color:#c0392b,font-weight:bold;
✓ visimark check
0 problems
Process completed with exit code 0
Every calculated value still agrees with its rule. The change merges.
Fail
✗ visimark check
26 problems (21 stale, 5 errors)
Process completed with exit code 1
The on-call-hours edit left 21 values behind. Run fmt, push, re-run.
Any document under the glob with a table and no rules is a failure too — there is
no strictness dial to find. The one way out is
<!--vmark:no-formulas-->, written in the file, so the decision is
about the document and not the CI run.
Works wherever Markdown works
GitHub, VS Code, pandoc
VisiMark adds computational semantics without taking Markdown away from the tools that
already understand it. Readers don't need VisiMark to read the document — verified
against GitHub, VS Code, pandoc and four other renderers.
GitHub
✓ pass — anchors stripped from output
VS Code preview
✓ pass — anchors pass through as a comment
pandoc → html5
✓ pass — anchors pass through as a comment
Charts and imports
Generated artifacts and external data, both verified
A chart statement draws an SVG straight from a sheet's own columns, kept
honest by fmt and check the same way any other derived value
is. A from clause does the reverse: a sheet's rows come from an external
CSV instead of a GFM table, pinned by hash so a change outside VisiMark's view is never
silent.
example-charts.md
Rendered preview
The SVG is drawn by fmt and checked byte-for-byte by
check — change a cell and the picture goes STALE until
it's regenerated.
from replaces the table entirely — the rows live in a CSV, and the
fence line pins its exact bytes:
No column rules here — Net, VAT and
Gross are read-only inputs from the CSV; only the
SUM aggregates run in the document. A changed byte in
invoice.csv fails check with STALE, or
IMPORT if the hash clause is missing entirely.
Power tools
Eight ways in, one engine
More to explore — each is one command, documented in full in the
CLI reference.
check
Verify calculations and fail on the first disagreement.
→ For your CI build.
fmt
Update stale calculated values while preserving the rest of the document.
→ To refresh calculations.
infer
Discover formulas from existing tables.
→ To power up your MDs.
eval
Inspect calculated values programmatically, including as JSON.
→ For your AI agent.
explain
Understand a sheet's inputs, rules and evaluation order.
→ As a cheat sheet.
chart
Generate a verified SVG from a sheet's own columns.
→ To manage artifacts.
Assertions
assert states an invariant a stray formula could still satisfy.
→ For your CI build.
VS Code extension
The same engine, as live diagnostics, quick fixes and hover.
→ Power up your editor.
Demonstration
Two documents from the repository, beside what they render to — scrolling in
lockstep, not screenshots.
Guarantee of artifact integrity
A picture derived from the data, and proven to match it
A chart statement names columns the sheet already has.
fmt draws the SVG and check proves the bytes on disk are still
what the current table renders to — so the picture cannot quietly drift away from
the numbers underneath it.
docs/example-charts.md
Rendered preview
docs/example-charts.md as committed, rendered client-side with
marked.
Executable documentation
The document is the source; tooling reads it directly
An operating budget where the worker-node count is derived rather than typed. The prose
is the specification, the tables are its inputs, and eval hands the results
to whatever needs them next — documentation to computation to machine-readable
output, not code to generated documentation.
docs/example-executable-documentation.md
Rendered preview
The same document, read by the CLI instead of a browser:
Install the visimark command globally, or run it without installing at all
— either way it runs under whichever of Bun or Node is on your PATH.
$ npm i -g visimark
# or
$ bun add -g visimark
# or, with no install at all
$ npx visimark check invoice.md
As an agent skill
VisiMark ships an agent skill — copy it in, and an agent picks up authoring and
verification discipline automatically, no prompting required.
$ cp -r skills/visimark ~/.claude/skills/visimark
Its central warning is worth stating here too: a green check is evidence of agreement,
not of derivation. Change an input and confirm the checker starts complaining before
trusting a document is wired up.
A chart statement turns a sheet's own columns into an SVG.
fmt draws it; check proves the bytes on disk still match the
data — the same guarantee as any other computed value, just shaped like a
picture.
Anchors
A comment anchor binds a printed number to a name, so a sentence stays plain prose
while the value stays machine-checkable:
The HTML comment is invisible in every renderer that permits raw HTML — GitHub,
VS Code, pandoc — so a reader just sees the bold number.
Assertions
Every number agreeing with its own formula is not the same as the document being
right. An assert states the invariant the numbers together must satisfy
— it binds nothing and fmt never touches it:
Without it, a payment schedule that stopped summing to the invoice total would leave a
non-zero variance and still pass. With it, check shows the
expression and the values that broke it:
ASSERT #recon variance == 0-318.00 == 0 is false
VS Code extension
One language server wraps the same engine, so the editor disagrees with you as you
type rather than at commit time — live diagnostics, quick fixes, inlay hints,
CodeLens and hover, with fmt behind the editor's own format-on-save.
STALE lines.Net · On-call support
3120.00 ≠ 5200.00 Qty * Rate
Quick fix: update the value to 5200.00
Not on a marketplace yet — build and install it from a clone with
bun run vscode-install, then reload the window.
Numbers should be derived, not trusted.
VisiMark makes calculations explicit, changes reviewable, and numerical correctness
enforceable — while keeping the document as plain Markdown.
