Turns HTML and CSS into a PNG without a browser in the loop. One Rust binary, one process.
0.3.0-beta.10, one maintainer. Linux x86_64, glibc ≥ 2.35.
printf '<h1>hello</h1>' > t.html # the argument is a path, not a URL; a missing file panics (101)
html-render assets/hero.html hero.png 1600 900 2 --document # the PNG aboveGetting a page into an image inside CI usually means shipping a browser: several hundred megabytes of image, a JavaScript engine the job never calls, a cold start ahead of the first pixel, and a runtime to install before any of it.
This one reads a file and writes a PNG. On an 8-slide deck its peak is at least 31× less memory
than headless Chromium (the measurements), and deck and probe both ship in this
repo, so python3 tools/bench.py re-derives every row.
Decks, social cards, report one-pagers, CI visual diffs: HTML plus CSS in, an image out.
Linux x86_64 with glibc ≥ 2.35: Ubuntu 22.04+, Debian 12+, or a current Fedora. Anything else wants the container below.
V=v0.3.0-beta.10
N=html-render_0.3.0-beta.10_linux_amd64
BASE="https://github.com/leshchenko1979/html-render/releases/download/$V"
curl -fsSL -O "$BASE/$N.tar.gz" -O "$BASE/checksums.txt"
sha256sum -c checksums.txt && tar xzf "$N.tar.gz"
install -m755 html-render /usr/local/bin/ && html-render --versionProvenance is checkable without a key: each release asset is attested by the release workflow's own
OIDC identity, with GitHub as issuer. The checksum catches a damaged download; the attestation
names the repository, commit and workflow behind the build. Both need the gh CLI.
gh attestation verify "$N.tar.gz" --repo leshchenko1979/html-render
gh attestation verify checksums.txt --repo leshchenko1979/html-renderThe release job applies both to the file it downloaded, so a release missing one fails before publication.
The binary names six libraries directly — libc, libssl, libcrypto, libfontconfig, libm, libgcc_s — and
pulls freetype, expat, libpng, bzip2, brotli and zlib through fontconfig, so ldd lists 12 of them on bookworm and 13
on jammy. A slim Debian or Ubuntu host needs one extra package line:
apt-get install -y libssl3 libfontconfig1 libfreetype6 libpng16-16 libbz2-1.0 libbrotli1 ca-certificates
The image carries those libraries and a font, but no network policy: a document's sub-resources are fetched at render time, so the container does not isolate egress (#29).
docker run --rm --user "$(id -u):$(id -g)" --cap-drop ALL --security-opt no-new-privileges \
-v "$PWD:/work" ghcr.io/leshchenko1979/html-render:v0.3.0-beta.10 \
/work/card.html /work/card.png 1280 720 2--user is not decorative: the image's own uid is 10001, and omitting the flag exits 101. Two tags
exist, v0.3.0-beta.10 and latest. A moving tag lets two builds of one commit disagree, so pin the
version, or the digest when the image itself must be frozen. The tarball's attestation does not extend to the image,
so verify that one by digest (#31).
Building from source: CONTRIBUTING.md.
The viewport is given in CSS pixels. Scale multiplies output resolution, and a single-image run may leave it out. Sub-resources are fetched at render time with no allowlist, so an untrusted document reaches the network by design.
html-render page.html out.png 1280 720 2 # one PNG
html-render --clip deck.html slides/ 1280 720 2 'section.slide' # one PNG per match
html-render --clip deck.html slides/ 1280 720 2 'section.slide' --per-element # element-sized canvases--clip writes slides/clip_01.png, clip_02.png and so on, numbered from 01 in document order. The three
shapes differ in memory: --full holds least, 37.6 MiB, then --per-element at 47.4 MiB; --clip holds most,
75.5 MiB, because it keeps one canvas as wide as the widest match. --full paints one image down to the
document's full height, in row bands, streamed to the encoder, so page height is not a memory limit and has no
ceiling; a position:fixed element forces one canvas instead, and says so.
On one host the output is reproducible: hold the document, the font stack and the host fixed and the bytes repeat.
Vary any of the three and the digest moves, so a changed pixel in CI is one of them. For a 1280×640 card at
scale 2, the shape of assets/og.png at 2560×1280, change the numbers and nothing else.
The exit code is part of the contract, and CI tests it against a real binary:
| code | meaning |
|---|---|
0 |
a PNG was written, or --help / --version was printed |
2 |
bad arguments: unknown flag, --clip not first, --per-element outside --clip, --full with --clip, --document with --fragment |
3 |
the selector matched nothing |
4 |
output written but known to be incomplete: a sub-resource failed to fetch (404, DNS, connection refused), was refused as too large, a fetch hit BLITZ_DEADLINE_SECS, or a frame past 65,408 px was cut |
5 |
one canvas would exceed the renderer limit (65,408 wide, 65,532 tall) and nothing was written; with banding on, that means one band or one element is too large, or banding was disabled with BLITZ_BAND_MIB=0 |
101 |
panic: unparsable number, invalid selector, unreadable input |
html-render --help is the maintained list of flags. Six environment variables exist. Three change what is rendered: BLITZ_BAND_MIB (4), BLITZ_DEADLINE_SECS (120), BLITZ_MAX_IMAGE_MP (128). Three are diagnostics: BLITZ_DRAIN (quiet), BLITZ_RUNTIME (current-thread), BLITZ_TRACE (unset). --help also names BLITZ_BAND_MIB, in the passage that explains a refused band.
No --json, no manifest (#28). Two surfaces are machine-readable, and they sit on different streams: TIMING (parse, layout, paint, total, scale, mode, plus content_h=/canvas_h= when a document was cut) on stderr, and one line per frame on stdout under --clip:
clip_01 css x=0.00 y=21.44 w=400.00 h=38.00 physical 400x38 at 0,21
Nothing below is typed by hand: bench/results.json is a receipt that tools/bench.py wrote on a GitHub
runner, and the repo commits it unedited. The deck comes from a seed, so one command reproduces this document anywhere:
git clone https://github.com/leshchenko1979/html-render && cd html-render
python3 tools/bench.py --bin <path-to-render> --chrome <path-to-chrome> --out /tmp/mine.jsonA deck.html digest of b77aac2de5931588dfa01eb5af418bc5 means the same document as the receipt. Any other
digest means the generator moved, and the rows below describe a different document.
Eight slides at 1280×5760 CSS px, scale 2, three renders per engine; peak RSS sums every process the engine spawned:
| measurement | Chromium | html-render | ratio |
|---|---|---|---|
peak RSS, --full |
2350.8 MiB | 37.6 MiB | 62.52× |
peak RSS, --clip |
2350.8 MiB | 75.5 MiB | 31.14× |
peak RSS, --per-element |
2350.8 MiB | 47.4 MiB | 49.59× |
Memory carries the claim. At least 31× less in the least favourable mode, and 49× in the advertised one.
The band repeats: five runs of the probe on one runner image (43744837000, 43746767310, 43752965645,
43754284965, 43762042304) kept html-render's --full peak inside 37.6 MiB to 37.9 MiB, a 0.8 % spread,
while Chromium ranged over 2336 MiB to 2453 MiB.
Wall clock is measured, gated, and not advertised. The receipt carries it for both engines, and the drift check gates the wall ratio at a deliberately coarse 45 %: a 1.85× slowdown of this renderer trips it, a 1.80× one does not. Absolute seconds stay ungated, because on one host, one deck and one binary Chromium read 1.604 s on one run and 3.120 s on the next. A ratio that mostly reports the other program's load is not a property of this one.
Method, host and the run itself: GATES.md.
At the same viewport and scale, pixel for pixel against Chromium, the probe's deck differs on 4.7083 % of
pixels by more than 16 levels across 29,491,200 pixels. The mean channel difference is 8.2889; ink coverage
is 17.073 % (Blitz) against 16.6941 % (Chromium). This is the entire deck at full resolution rather than a
sample, and tools/bench_compare.py recomputes it from the two PNG sets.
Pixel divergence is what the deck measures. On this deck it is mostly antialiasing and glyph rasterisation;
how much of it is layout is not quantified here. The deck contains a border-collapse table, and table layout
is one of the known divergences below.
The reproducible number is the corpus. Every run measures geometry over 36 fixtures at one viewport,
against Chromium: the corpus agrees on 42 of its 54 text-free rows; 11 diverge and 1 asserts a shared
absence. tools/parity_baseline.json pins all 11 box by box, so a regression reddens the build while the
current defects stay visible. The divergence is not spread: one table accounts for 7 rows (#9), one
<br> run for 4 (#15).
- Linux x86_64 only. glibc ≥ 2.35 is the floor. No macOS or Windows build exists.
- No JavaScript. Script does not run; the document renders as the HTML that arrived.
- PNG only. No PDF and no print model:
@page, page boxes and page counters are all absent. - Blitz's CSS, not Chromium's. An unknown property is dropped, not rejected, so what a reader sees is a declaration with no effect.
- Linked against the host's libraries. Six libraries are named directly and the rest arrive through fontconfig, so
lddon your own host is the only accurate list. The container carries its own copy. - Beta. Flags and output names can move between minor versions; nothing here is a stable API.
- Nothing sandboxes the input. Sub-resources are fetched with no allowlist, and
file://can be read (SECURITY.md). No offline mode: a document controls its own outbound HTTP (#29). - Peak memory follows canvas area, not page length. The figures above count the whole process tree, but on one
deck. One 128 MP decode costs about 512 MiB of RGBA, and
clip_oversized_frameintools/memory_baseline.jsonpeaks at 809.5 MiB, 21× the 37.6 MiB headline. Budget a container from that. - Three defects exit
0with wrong pixels, all reproduced on0.3.0-beta.10: table layout, off by up to 18px and painting the table taller than Chromium does, 104 px against 86 (#9);<br>runs shifting content 16px per break (#15); and a200whose body is not an image, which fails to decode inside Blitz after the bytes were delivered, so nothing upstream of the decoder sees it (#27). The corpus gate pins #9 and #15; the non-image200has no test at all. - Taller than the canvas means a truncated PNG. The output keeps the requested
<width> x <height>at exit0, because every golden depends on that default, butTIMINGcarriescontent_h=<document px> canvas_h=<canvas px>and stderr names how many rows were lost (#10).--fullpaints the whole document instead. - A missing font is substituted, and named on stderr. fontconfig resolves a substitute rather than failing,
so a family the host lacks renders in whatever was picked, at exit
0, with a layout that still looks like a layout. Each such family is named once. Generic keywords and@font-facefamilies go unreported: there the substitution is the request being honoured. Exit stays0, and the caller decides. - A failed sub-resource exits
4(#11): a404, a DNS failure, a refused connection, or an image pastBLITZ_MAX_IMAGE_MPleaves a partial PNG and the resource named on stderr. - A frame wider than the viewport is written at its own width. The default
--clipband is as wide as the widest match, so a 1600 px element in an 800 px viewport comes out 1600 px wide, at a peak of one band. Beyond the renderer's 65,408 px limit no paint happens, so that residual case is still a cut, at exit4. - A killed render leaves a truncated PNG at the output path: no temp file, no rename (#26). No SBOM is generated and no dependency advisory scan runs in CI (#25).
| file | holds |
|---|---|
| GATES.md | determinism, device scale, element clip, cost, corpus, fidelity, CSS audit |
| CONTRIBUTING.md | build requirements, the CI workflows, the rules a change must pass |
| SECURITY.md | what rendering does to the machine, measured egress, reporting |
| CHANGELOG.md | what moved between releases |
| bench/README.md | the probe: what it measures, how to re-run it, what the bands mean |
| docs/why-html-first.md | what HTML-and-CSS-first rendering is good for, with sources |
A minimal HTML repro in a bug report is the most useful thing to send. Pull requests get read and reviewed, at the pace of one person on a beta; CONTRIBUTING.md lists the rules a change has to pass, and CONTRIBUTING.md#building has the build and the CI workflows.
Apache-2.0, with an explicit patent grant. Full text in LICENSE. The release tarball ships no licence text of its own (#32), so redistribute the LICENSE with it.
