Templates and imports

Typst documents pull shared layouts in with #import. typstgen decides where those files are found, based on template_paths in typstgen.toml.

Which template directories are used

1. typstgen reads the config: the file given with --config, otherwise ./typstgen.toml if it exists, otherwise the built-in defaults ./templates and ./.typstgen/templates.
2. Every entry of template_paths that exists and is a directory is used. Entries that are missing or point to a file are skipped.
3. Template directories are optional. A document without imports compiles even if none of them exists.

Relative paths are resolved against the working directory, not against the location of typstgen.toml. Run typstgen from the folder the config was written for, or use absolute paths.

Where imports are looked up

The input file becomes the root file of a small virtual filesystem. Every path in the document, #import "letterhead.typ" as well as #import "/letterhead.typ", image(…) or read(…), is looked up in these places, in this order:

1. the folder that contains the input file,
2. each template directory, in the order of template_paths.

Each file is looked up separately, so one document can import from several template directories. The first file that exists wins. .. cannot leave these folders.

project/
├── typstgen.toml          template_paths = ["templates"]
├── templates/
│   └── letterhead.typ
└── letter.typ             #import "letterhead.typ": letterhead

letter.typ finds letterhead.typ in templates/, because there is no file of that name next to it. This is the layout of the letter example.

If a file is found nowhere, Typst reports the virtual path it searched, with the position of the import:

error: typst compilation failed:
missing-import.typ:2:9: error: file not found (searched at /footer.typ)

Documents inside a template directory

When the input file lies inside one of the template directories, that directory takes the place of the input’s folder as the first root. Imports are then resolved relative to the input’s position in that directory, and paths starting with / from the directory itself; the other template directories remain fallbacks.

Typst packages

Package imports such as #import "@preview/…" are not resolved: typstgen has no package cache and does not download anything. Vendor the package files into your template directory and import them by path instead.