Prequery -- get outside information into your documents/"shell escape" for Typst

Hi! You may have heard about Prequery as a tool that can theoretically help you with fetching/preparing information from outside Typst for your document. Well, the “theoretically” part got a bit less significant:

Prequery now has an online documentation page (powered by Shiroa). If you had heard of it, the package is almost unchanged, but there is now also a command line tool to go along with it. Currently, it lets you download images (and other files) from the web and run arbitrary commands.

Downloading images from the web

Here’s an excerpt from the quickstart:

  • Use the Prequery package in your document:
    #import "@preview/prequery:0.2.0": image
    
    // toggle this comment or pass `--input prequery-fallback=true` to enable fallback
    // #prequery.fallback.update(true)
    
    #figure(
      image("https://example.com/example.png", "example.png"),
      caption: [An image],
    )
    
  • configure the web-resource preprocessor in a typst.toml file:
    [[tool.prequery.jobs]]
    name = "download"
    kind = "web-resource"
    
    (not shown: you also need a [package] section, even though prequery ignores it)
  • run the prequery tool to download the image:
    $ prequery main.typ
    [download] beginning job...
    [download] Downloading to example.png: https://example.com/example.png...
    [download] Downloading to example.png finished
    [download] job finished
    

Running Python commands

This is a bit less fleshed out, since you still have to handle the Typst side yourself, but the simplest case could look like this:

  • Configure the shell preprocessor:
    [[tool.prequery.jobs]]
    name = "python"
    kind = "shell"
    
    query.selector = "<python>"
    
    command = "python"
    format.stdin = "plain"
    format.stdout = "plain"
    
    The python command expects and produces plain text, not JSON, so the format is configured.
  • Put some code snippets as metadata in your document:
    #metadata((path: "out.json"))<python>
    
    #metadata((data: ```py
    print("Hello World")
    ```.text))<python>
    
    #metadata((data: ```py
    print("Hello Prequery")
    ```.text))<python>
    

This and a more complete example (where the snippets are executed in sequence and can share state) is explained in more detail on the shell preprocessor page.

Related Work

I want to give a shout-out to some other projects in this/similar domains.

  • ctxjs, jogs and pyrunner are JS and Python runtimes that let you run code in Typst as an alternative to escaping the sandbox. Pintorita for example can render diagrams from within Typst; Prequery now also brings PlantUML into the reach of Typst. It can’t run inside Typst because there’s no WASM-compatible JVM (that I know of).
  • I find jlyfish especially impressive, as it implements a watch mode to automatically re-evaluate Julia code. Prequery doesn’t have that yet (and I’m kinda afraid of the required complexity), so for Julia in particular jlyfish is the way to go. For Python notebooks and other tasks, Prequery could be your option.

So if you’re looking to get information into your document in a more automated way, I hope either Prequery or one of the other tools here can be of help! :slight_smile: Let me know if you have any questions. I tried to make the documentation approachable, but I’m sure there’s lots of room for improvement!

8 Likes