criterion-markdown

criterion-markdown reads Criterion benchmark JSON output from target/criterion and renders a markdown summary table.

What It Does

• Walks a Criterion result directory and discovers benchmark runs.
• Reads benchmark.json, estimates.json, and optional change/estimates.json.
• Produces grouped markdown tables with human-readable timings and change indicators.

Usage

This crate exposes two entrypoints:

• criterion_markdown::render(criterion_dir, allowlist) — render with default options.
• criterion_markdown::render_with_options(criterion_dir, allowlist, &options) — render with custom [RenderOptions].

Where:

• criterion_dir points to a Criterion output directory (for example, target/criterion).
• allowlist is an iterable of benchmark ids (Vec<String>, &[String], Vec<&str>, etc.). If empty, no filtering is applied.

Options

RenderOptions has the following fields:

• collapsible: Option<String> — if set, wraps the output in a <details><summary>…</summary></details> tag using the provided value as the summary text. The summary tag also includes the best/worst change range.

Example

use criterion_markdown::RenderOptions;

fn main() -> anyhow::Result<()> {
    // Basic usage
    let markdown = criterion_markdown::render("target/criterion", std::iter::empty::<&str>())?;
    println!("{markdown}");

    // Collapsible output
    let options = RenderOptions {
        collapsible: Some("Benchmark Results".into()),
    };
    let markdown = criterion_markdown::render_with_options(
        "target/criterion",
        std::iter::empty::<&str>(),
        &options,
    )?;
    println!("{markdown}");

    Ok(())
}

How This Differs From criterion-table

• This crate reads benchmark data directly from the JSON files generated by Criterion in target/criterion.
• It does not depend on cargo-criterion.
• This crate is a library you can embed and call from your own project code; criterion-table is primarily used as a standalone binary tool.
• You can point it at an existing Criterion output directory and render markdown without changing how benchmarks are run.

Development

Run checks locally:

cargo +nightly fmt --check
cargo test
cargo clippy --all-targets -- -D warnings