A command-line (and a Makefile rule) to build thumbnails

General
1

If you want to submit a Typst template to the package repository, the packaging rules ask for a thumbnail – a picture of the first page of a typical document using your template.

I looked online for instructions on how to automatically generate a suitable image from a .typ document, and did not find any. Here is what I came up with, in case it can help others:

Suppose you want to turn foo.typ into foo-thumbnail.png. Use the following:

typst compile foo.typ
magick -density 250 foo.pdf[0] -flatten foo-thumbnail.png
oxipng -o 2 foo-thumbnail.png

Explanations:

  • magick is the non-deprecated way to invoke ImageMagick’s convert utility
  • -density 250 asks for 250 dpi, as recommended
  • the [0] part of foo.pdf[0] selects the first page only
  • -flatten replaces a transparent background by a white background
  • oxipng optimizes/compresses the PNG, as recommended
  • -o 2 is an optimization level that runs fast and produces good results (using -o max is much slower and the result is not shorter)

In case it helps, I have a rule in my Makefile to do this:

%-thumbnail.png: %.pdf
	magick -density 250 $<[0] -flatten $@
	oxipng -o 2 $@
2 Likes
2

I went ahead and submitted a PR to include these instructions in the package repository: README.md: document a command-line script to produce thumbnails by gasche · Pull Request #2007 · typst/packages · GitHub

3

fyi, unless I’m missing the purpose you can combine the compile and extract steps to

typst compile --pages 1 --ppi 250 foo.typ foo-thumbnail.png

Also related: for packages, where 250 dpi and a single thumbnail is not mandatory, creating dark and light mode thumbnails can be nice. the community’s package template contains the setup for you :slight_smile:

1 Like
4

I was pointed at typst compile foo.typ foo.png on the github as well, but I notice that it generates fairly large png files. At the recommended resolution my example takes 2Mio, compared with 250-300Kio with ImageMagick.

I didn’t know about typst-package-template, thanks! Could it maybe be documented in the README of GitHub - typst/packages: Packages for Typst. ?

(From a distance I don’t really understand how to use thumbnail.typ. Is the expectation that typst packages would generally handle both a light and a dark mode, so that they can adjust their own settings accordingly, and use that in the demo file used to generate the thumbnail?)

1 Like
5

Thanks, that was the info I was missing! Is the difference still noticeable after oxipng?

Well, it’s a community template. There’s benefit in mentioning it, but it’s also understandable that Typst-the-company is reluctant in endorsing specific non-official projects. I don’t think even Tinymist is mentioned in the docs? (Although one could argue that Tinymist “competes” with the web app, but I don’t think that’s the deciding difference.)

No, unless the package has a use to do that. The idea is that you want to showcase your package on a website, and if that website supports dark mode, the showcase should fit the user’s preference. Take Alexandria: this package is about bibliography and has nothing to do with themes, but on the website you want to present it nicely. So thumbnail.typ, not the package is responsible for theming. The thumbnail is basically a document using the package, not part of it. And this document supports dark mode.

Obviously you’re free to remove that from your package if you want, but it seemed useful enough to include it by default, so that having a dark mode thumbnail is easier to accomplish.