path

A file system path.

When splitting up your project or package across multiple files, or referencing resources such as images or bibliographies, you'll need to interact with paths.

Path strings

Commonly, paths are simply expressed as strings. Built-in functions that expect paths typically also accept strings. For instance, you can write:

#figure(
  // Path to an image
  image("tiger.jpg"),
  caption: [A tiger],
)

// Path to a Typst file
#include "chapter.typ"

There are two kinds of such path strings: Relative and absolute.

• A relative path resolves in relation to the parent directory of the Typst file where the function is called. While this is the default, a path can also be explicitly specified as being relative by starting it with ./.

  #image("images/logo.png")
  #image("./images/logo.png") // This is equivalent
  

• An absolute path always resolves relative to the root of the project. Such a path is indicated by a leading /:

  #image("/assets/logo.png")
  

Paths consist of segments that are separated by forward slashes, with interior segments indicating directories and the final one a file or a directory. There are two path components that are treated specially:

• The segment . refers to the current directory. This is why "./image.png" and "image.png" are equivalent.

• The segment .. refers to the parent directory. If you have three files main.typ, utils.typ, and text/chapter1.typ, then you can reference your utility file from chapter 1 through the path "../utils.typ".

The path type

For most typical usage of paths, strings are all you need. However, sometimes you need a bit more control. For instance, you may want to resolve a path relative to the file you are currently writing in, but then pass it to a package and let the package read from the path. This is where the path type comes in.

With it, you can fully resolve a path string relative to the file where you construct it. Any following operations performed with the path (such as a file read or an image load), will then behave the same regardless of where in the code they occur.

Here's an example of how we could have a main.typ with a data.json file directly next to it and still let a package we've built read that file.

// This is main.typ, with data.json next to it.
#import "@local/my-pkg:0.1.0": process
#let data-path = path("data.json")
#process(data-path)

Roots

The project root

For security and reproducibility reasons, Typst encapsulates file access. A Typst project can only access paths within its project root. If you try to create or access a path outside of this root, you'll get an error:

// ❌ Error: path `"../secret.txt"` would escape the project root
#path("../secret.txt")

By default, the project root is the parent directory of the main Typst file. If you wish to use another folder as the root of your project, you can use the CLI's --root flag:

typst compile --root .. file.typ

Make sure that the main file is contained in the folder's subtree, so that Typst can access it.

In the web app, the project itself is the root directory. You can always read all files within it, no matter which one is previewed (via the eye toggle next to each Typst file in the file panel).

Package roots

Just like the project, each package you import has its own root. Within a package, absolute paths point to the package root rather than the project root. On its own, code in a package cannot construct a path that lives in the project or another package.

If you need to provide a package with resources from the project (such as a logo image), you can do so by explicitly creating a path to the resource in your code with the path constructor. You can then pass the resulting path to the package. An example of this is shown in the section "The path type" above.

Alternatively, you can perform the path operation in your code and pass the result to the package. This could, for example, be the result of a read call or a complete image (e.g. as a named parameter logo: image("mylogo.svg")). Note that if you pass an image to a package like this, you can still customize the image's appearance with a set rule within the package.

Further operations

For now, the path type's purpose is limited to correctly handling and transferring paths across files in your project and packages. In the future, it may enable additional capabilities like checking for the existence of a file or enumerating files in a directory.

Creates a path from a string.

// A relative path without a leading slash.
// May optionally start with `./`.
#path("relative/path/to/file.typ")
#path("./relative/path/to/file.typ")

// An absolute path with a leading slash.
#path("/absolute/path/to/file.typ")