specify compiler options via in-file metadata header

[gasche]

Description

Many options that affect the build of a Typst document can be passed via command-line options to typst compile or typst watch. For example: --root <root>, --ppi <PPI>, --features <feature>. But sometimes it would be much easier, in particular for tooling support, to be able to specify those options directly in the file, in some header metadata:

#document-header(
  root: "..",
  features: ["html", "ally"],
)

(rest of the document)

The document-header comment must be placed first in the file (with optional comments before and inside), so that it can be located without interpreting the whole file. (A bespoke lexical syntax for metadata could also be designed, see Pandoc metadata block.)

If options are provided via both the command-line and the document header, then the file header settings take precedence.

Use Case

My Emacs typst-ts-watch mode fails on the following error for a given file:

error: failed to load file (access denied)
    ┌─ slides.typ:652:14
    │
652 │ #bibliography("../suspended.bib", title: none, style: "./gasche-author-date.csl")
    │               ^^^^^^^^^^^^^^^^^^
    │
    = hint: cannot read file outside of project root
    = hint: you can adjust the project root with the --root argument

Unfortunately typst-ts-watch does not currently provide support for specifying the --root parameter when it invokes typst watch. I will of course request such support in that particular tool, but there are dozens of tools out there (editor modes, linters, build system integrations, etc.) that will each need to be extended to support specific command-line options for the typst CLI, while these options could be passed once and for all in the file itself.

[cady-b]

This would violate the security model¹: https://typst.app/open-source#faq:~:text=We%20take%20special%20care%20to%20ensure
It would effectively allow any document to read arbitrary files on the system (and, for example, embed them invisibly into the output, thereby exfiltrating data).

However, you can already (since v0.3.0) set the TYPST_ROOT environment variable to change the root without messing about with the final stages of your tooling. TYPST_FEATURES is available to enable features.
Version 0.14.0 introduced the typst info subcommand, which allows you to inspect this and other information. The manual and --help also show which flags are available (next to their corresponding arguments), i.e., https://man.archlinux.org/man/extra/typst/typst-compile.1.en

If you really want to specify this from the document, parsing the header manually, then setting these before compiling should be quite doable; else this would be something to ask in the typst-ts-watch project.

Footnotes

1. It was possible to read outside the root in the past, but this was reverted with 04bffc4 in response to security: Restrict arbitrary file reading #219 and related issues from that time; introducing this feature would bypass the fix. There are a couple of open issues to relax the current rules, but changing the root is quite drastic and unlikely to be implemented.
   Features are less sensitive security wise, but I think the user should still be in control of experimental stuff being used or not; they are gated for good reason. ↩

[gasche]

Okay, I see how that is a problem for that particular desired security model. Closing.

[T0mstone]

I agree that --root would be an issue, but I think there's still a good case for --features, --ppi, and --format (where the latter two would change the default value).

[cady-b]

@T0mstone discussion around that may be found in #4174 (but with a slightly different interface)

[T0mstone]

Not really the part about --features, but I've added my comment about --format there.👍