Skip to Content
Takumi

Use takumi in scripts

Pipe HTML in and images out, read the exit codes, and fail a build on a file a document cannot load.

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 input

- 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 output

-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 codes

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.
WarningWhat the render did
A file that did not loadLeft out the image, font, or style sheet.
An unsupported propertyDropped the declaration, as a browser drops one it does not know.
A character no font drawsDrew an empty box in its place.

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

Fail on a warning

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 did

--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 "Segoe UI Emoji", 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
StageWhat debug adds
styleEach value, rule, and utility class the parser dropped. 1
fontEach font file loaded, and each later font-family name with no loaded face. A missing first name warns without --log.
imageEach image loaded, and each one a box asked for that was not.
layoutThe size of the canvas, or of each PDF page with why it ended.
paintHow many chunks each paint pass draws.

1 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 warns only when it comes first in a font-family, since that is the font the style asks for. A generic family, -apple-system, and BlinkMacSystemFont never warn. A later missing family only falls back to the next one, as CSS says, so it shows only as a debug line. 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 codes

The exit code tells a script why a render failed:

CodeMeaning
0The output was written, or the listing printed.
1The render failed. 1
2The command line is wrong. 2
3The document tried to read a file outside the directories you granted.

1 For example, an input that does not exist, a file past the size limits, or a warning under --deny-warnings.

2 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 CI

--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 files

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

mkdir -p out || exit
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.

Last updated on