Reports

Turn a Markdown or JSON report into one HTML page built from the report blocks, for anything a person is handed to read.

Steps

Write it as Markdown

A title, a summary paragraph, then ## sections. Tables, > [!NOTE] callouts and stats, timeline and decisions blocks become report blocks.

# Status

One paragraph that says where things stand.

## What needs your call

```decisions
Deploy the preview?
Default: Yes
Options: Keep it local
Why: It is ready.
```

2
Run kh-report
One command, from this repository (or by its path from any other). It builds the renderer on first use.
```
npx kh-report status.md -o out/index.html --open
```
3
Or give it JSON
The same page from data: a title, a summary and sections of { type, props } for the report blocks. A bad section stops the build and names its path.
```
{ "title": "Status", "summary": "…",
  "sections": [{ "type": "report-callout",
    "props": { "tone": "note", "title": "", "text": "Hello" } }] }
```

What you get

A document, not a dashboard: a readable column, calm spacing, and it prints.

One file

The page has its CSS inlined, no JavaScript and no request to anywhere, so it opens from a file, mails as an attachment and prints to PDF as it looks. Fonts are the system stack.

The blocks

Report header, key figures, decisions with a recommended default (answerable on the page, with --seat), a table for long cells (cards on a phone), timeline, callout, sources and prose. See the Report category under Blocks.

Markdown conventions

The first paragraph is the summary; a Meta: line carries Kind, Date, Author and Ref. A list under a Sources or References heading becomes numbered sources. Anything else is prose, with bold, code and links drawn as such.

Copy for AI