# 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
```rust
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:
```bash
cargo +nightly fmt --check
cargo test
cargo clippy --all-targets -- -D warnings
```