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 the render went on without something the document asked for:

warning: ignored the property `widht` at line 4, column 13 of its style sheet or `style` attribute, since takumi does not support it. Check its spelling.
warning: no font draws 你 (U+4F60), 好 (U+597D), so each shows as an empty box. Pass a font that does with `--font`, or check the `font-family` of that text.

Each warning prints once. -q hides warnings and keeps errors.

Fail on a warningCopy Anchor Link

A warning leaves the exit code at 0, since the output was written. --deny-warnings makes any warning a failure. The command prints its warnings, writes no output, and exits with 1:

takumi image card.html -o card.png --deny-warnings

-q hides the warnings and --deny-warnings still counts them.

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 property `cursor`, which changes nothing in a render
[     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. An unsupported property is a warning instead, unless it could not change a render, such as cursor or transition, which is listed here. A vendor-prefixed property such as -webkit-font-smoothing is not listed at all.

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, a file past the size limits, or a warning under --deny-warnings.

² 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 allowed in the second field for a file that would load. This step fails when any file would not:

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

if [ -n "$unloaded" ]; then
  printf '%s\n' "$unloaded"
  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.