HTML Report

The HTML report is a core deliverable — the document you are reading right now is generated by this system. The goal is to show an "executed specification," not a "test log."

After running specs, specdown generates a multi-page HTML site. Output path and format are set in the project configdepends. Each spec file becomes a separate HTML page, with shared CSS and JS assets. Prose is preserved as-is; only execution results are annotated with status.

This page itself is an example of the report. Here is what to look for:

Sidebar (left) — lists every spec page with colored status dots. Documents in subdirectories are grouped; groups are collapsible and show aggregated status. See TOC Groupingdepends for configuration. When a document has a frontmatter type, a colored badge appears next to its title
Header bar — shows the run timestamp and aggregate pass/fail/xfail counts as colored pills
Section headings — carry a colored left border: green for pass, red for fail
Executable blocks — a green left border means the block passed; red means it failed. Blocks with a summary line render collapsed and can be expanded with the > marker
Check tables — each row shows pass/fail individually; failed rows display expected/actual diff inline
Alloy badges — Alloy check results appear as small status badges next to the relevant section
Footer — links to the project repository

Multi-page Structure

Each document becomes a separate HTML page. Shared assets (style.css, script.js) are written to the output root directory.

Generate a minimal report for structure verification

mkdir -p .tmp-test
cat <<'SPEC' > .tmp-test/report-test.spec.md
# Report Test

A minimal spec for testing report generation.
SPEC
printf '# Report Test\n\n- [Report](report-test.spec.md)\n' > .tmp-test/index.spec.md
cat <<'CFG' > .tmp-test/report-test.json
{"entry":"index.spec.md","adapters":[]}
CFG
specdown run -config .tmp-test/report-test.json -out report-out 2>&1 || true

run:shell

$ test -f .tmp-test/report-out/style.css && echo yes

yes

$ test -f .tmp-test/report-out/report-test.html && echo yes

yes

run:shell

The report must be readable without JavaScript — all headings and content render in plain HTML.

Summary Lines

Blocks whose first line is a comment render collapsed in the report. The summary text and pass/fail indicator are visible; a > marker lets readers expand the block. Failed blocks auto-expand.

Link Rewriting

Markdown links to .md and .spec.md files are rewritten to .html in the output.

Output Files

File	Description
`<outDir>/style.css`	Shared stylesheet
`<outDir>/script.js`	Shared JavaScript
`<outDir>/<page>.html`	Per-document HTML pages
`<outDir>/report.json`	Machine-readable results
`.artifacts/specdown/models/*.als`	Combined Alloy models
`.artifacts/specdown/counterexamples/*`	Counterexample artifacts (on Alloy check failure)

When trace is configured, each spec page gains a sticky Traceability panel on the right side showing the document's parents (incoming edges), the current document highlighted, and its children (outgoing edges) with relationship labels.

Failure Diagnostics

When an adapter returns expected/actual values on failure, those values appear in both the CLI output and the JSON report.

The CLI output format for check table failures includes the row number and optional label:

  FAIL  Heading > Path  [check-name] row 5 "description"
        error message
        expected: expected-value
        actual:   actual-value

The HTML report renders expected/actual as an inline diff. The JSON report includes expected, actual, and label fields for programmatic consumption.