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.pngA 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 assetsWrite 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.gztakumi 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.| Warning | What the render did |
|---|---|
| A file that did not load | Left out the image, font, or style sheet. |
| An unsupported property | Dropped the declaration, as a browser drops one it does not know. |
| A character no font draws | Drew 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| Stage | What debug adds |
|---|---|
style | Each value, rule, and utility class the parser dropped. 1 |
font | Each font file loaded, and each later font-family name with no loaded face. A missing first name warns without --log. |
image | Each image loaded, and each one a box asked for that was not. |
layout | The size of the canvas, or of each PDF page with why it ended. |
paint | How 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:
| Code | Meaning |
|---|---|
0 | The output was written, or the listing printed. |
1 | The render failed. 1 |
2 | The command line is wrong. 2 |
3 | The 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
fiRender 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