Provedown

Markdown-native verifiable literate documents. Agents or people create markdown/HTML/text reports, attach small executable evidence to the claims that matter, and let a deterministic verifier check the numbers.

Start the tutorial Read the markup contract

Install And Run

Install with pipRun with uvx

pip install provedown
provedown verify report.md

Run the verifier directly from PyPI without installing it into the current environment:

uvx provedown verify report.md

What It Does

Provedown keeps the human-readable document as the source of truth. Values in prose are authored claims, not generated render output, and verifier plugins can recompute those claims from embedded evidence.

Styled reader view

orders = [
    {"status": "paid", "amount": 120},
    {"status": "refunded", "amount": 45},
    {"status": "paid", "amount": 75},
]
paid = [order for order in orders if order["status"] == "paid"]
total = sum(order["amount"] for order in paid)

The report includes 2 paid orders totaling $195.

Provedown source

<pre><code>
orders = [
    {"status": "paid", "amount": 120},
    {"status": "refunded", "amount": 45},
    {"status": "paid", "amount": 75},
]
paid = [order for order in orders if order["status"] == "paid"]
total = sum(order["amount"] for order in paid)
</code></pre>

The report includes <span class="result" data-code="len(paid)">2<span class="method"></span></span> paid orders totaling <span class="result" data-code="f'${total}'">$195<span class="method"></span></span>.

The styled reader view is a documentation preview, not the default output of every Markdown viewer. Pandoc renders the same source shown alongside it, then this site's CSS hides the <pre> block and accents the result spans. GitHub and other viewers that do not load that CSS show the code and render the claims as ordinary prose.

In the source, <code> marks executable evidence and <pre> preserves its multiline layout for readers. Reader-first reports can make that block expandable or hide it from rendered output; the rendering guide shows each option alongside its source.

If the data or filtering logic changes, provedown verify catches stale prose before it ships.

Find Your Path

• Learn the loop

  Create a first report, run the verifier, and see how mismatches are reported.

  First verified report

• Use real inputs

  Import standard-library modules, read local CSV files, and verify prose claims against computed summaries.

  Python modules and data files

• Inspect and lint

  Understand which code supports which claims, then catch fragile document structure before verification.

  Inspect dependencies

• Check the contract

  Review the recognized HTML elements, attributes, comparison policies, and CLI behavior.

  Markup contract

• Understand hallucination checks

  See how Provedown turns important prose claims into values that deterministic tools can challenge.

  Hallucination detection

Documentation Map

This documentation follows the Diataxis structure:

• Tutorials teach new workflows step by step.
• How-to guides solve focused operational tasks.
• Reference describes stable APIs, commands, and file formats.
• Explanations discuss design choices and tradeoffs.

The project is still early, so examples and reference pages describe what exists today while design notes track where the format is heading.