Use takumi in scripts

takumi is built to sit in a pipeline. The rendered file is the only thing it writes to standard output, messages go to standard error, and the exit code tells a script what went wrong.

Read from standard inputCopy Anchor Link

- as the input reads the HTML from standard input. Here generate-card stands for any program that prints HTML:

generate-card --title "Launch day" | takumi image - -o card.png

A document read from standard input gets no readable directory, since it has no file to sit beside. If it references stylesheets, images, or fonts, grant their directory with --root. Relative URLs then resolve against the working directory:

generate-card | takumi image - -o card.png --root assets

Write to standard outputCopy Anchor Link

-o - writes the output to standard output. There is no file extension to read the format from, so an image needs --format. This example compresses the image with gzip on its way to a file:

takumi image card.html -o - --format svg | gzip > card.svg.gz

takumi pdf always writes PDF, so it needs no --format. Neither command writes binary output to a terminal. Redirect it to a file or a pipe.

Messages and exit codesCopy Anchor Link

Warnings and errors go to standard error, starting with warning: or error:. A warning means a file was skipped and the render went on, such as a missing image. -q hides warnings and keeps errors.

What a render didCopy Anchor Link

--log info prints one line to standard error for each stage, with the time since the command began:

takumi image card.html -o card.png --log info

[     0.6ms] input: read file:///site/card.html, 290 bytes
[     5.1ms] stylesheet: style sheets loaded: 1
[    10.2ms] resource: images loaded: 1
[    20.0ms] render: rendered 4339 bytes
[    20.1ms] output: writing card.png

--log debug adds a line for each style sheet, font file, and image loaded, and for what the render dropped or did not find:

[     4.7ms] style: ignored the unknown property `widht`
[     5.7ms] style: `bogus-utility` is not a utility takumi knows
[     6.2ms] style: ignored `display: flexx` at line 2, column 32 of its style sheet or `style` attribute
[     6.9ms] font: no face is loaded for font-family "Inter", so text uses Geist
[     7.8ms] image: no image is loaded for "missing.png"
[    11.6ms] layout: page 1 has a 718.1102x1046.9292px page area
[    11.6ms] layout: page 1 ends at a forced break
[    12.0ms] layout: page 2 is full, so its content continues on the next page
[    12.2ms] paint: painting 12 chunks

¹ A line number counts from the start of its <style> element or file. A vendor-prefixed property such as -webkit-font-smoothing is not listed.

A missing font family is not a warning, since text falls back to the next family as CSS says. The debug line is where it shows. Each debug line prints once, however many boxes reach it. The word before the colon is the stage, so grep '] font:' keeps one stage.

Exit codesCopy Anchor Link

The exit code tells a script why a render failed:

¹ For example, an input that does not exist, or a file past the size limits.

² For example, an unknown flag, a value CSS does not accept, or an output format takumi does not write.

Code 3 separates a policy failure from a broken document, so a script can retry with --allow-read, or report the document as untrusted. See Control file access.

Check a document in CICopy Anchor Link

--list-resources prints one tab-separated line for each file the document would load, with blocked in the second field for a file that would not load. This step fails when any file would be blocked:

listing=$(takumi image page.html --list-resources) || exit
blocked=$(printf '%s\n' "$listing" | awk -F '\t' '$2 == "blocked"')

if [ -n "$blocked" ]; then
  printf '%s\n' "$blocked"
  exit 1
fi

Render many filesCopy Anchor Link

Each run renders one file, so a shell loop covers a directory:

for page in pages/*.html; do
  takumi image "$page" -o "out/$(basename "$page" .html).png" --width 1200 --height 630 || exit
done

|| exit stops the loop at the first failure and keeps its exit code.