Templates and imports
Which template directories typstgen uses and where it looks for the files a document 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
- typstgen reads the config: the file given with
--config, otherwise./typstgen.tomlif it exists, otherwise the built-in defaults./templatesand./.typstgen/templates. - Every entry of
template_pathsthat exists and is a directory is used. Entries that are missing or point to a file are skipped. - 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:
- the folder that contains the input file,
- 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.
Focus
Source: src/config.rs (template_roots), src/world.rs, docs/guides/templates.mdx, examples/missing-import.txt
Show chart data
| Step | Kind | Leads to |
|---|---|---|
| #import "letterhead.typ" | start | Next to the document? |
| Next to the document? | decision | First match is used (yes), In the first template dir? (no) |
| In the first template dir? | decision | First match is used (yes), In the next one? (no) |
| In the next one? | decision | First match is used (yes), file not found (none left) |
| file not found | end | |
| First match is used | end |
Focus
Source: src/config.rs (template_roots), src/world.rs, docs/guides/templates.mdx, examples/missing-import.txt
Show chart data
| Step | Kind | Leads to |
|---|---|---|
| #import "letterhead.typ" | start | Next to the document? |
| Next to the document? | decision | First match is used (yes), In the first template dir? (no) |
| In the first template dir? | decision | First match is used (yes), In the next one? (no) |
| In the next one? | decision | First match is used (yes), file not found (none left) |
| file not found | end | |
| First match is used | end |
project/
├── typstgen.toml template_paths = ["templates"]
├── templates/
│ └── letterhead.typ
└── letter.typ #import "letterhead.typ": letterheadletter.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/cetz:0.4.2" are resolved like in the typst CLI, from
the same package directories. See Packages and bibliographies. The
Wasm build has no package directories: vendor the package files into the virtual filesystem and
import them by path.