Global path in module includes

At the moment, the following is not possible:

#include "/home/usr/foo.typ": foo

This should probably be a feature, and should be handled in two ways:

• Paths prefixed by / should be an absolute path from root.
• Paths prefixed by ~ should be a path relative to the current users $HOME.

I can fix this if this is an intended feature.

When you add double slash // at the start of the path, it gives you access from the root. Without the double slash it does not work. I think this is a bug.

Here is the underlying code for this in src/eval/mod.rs, so yes, adding // does give you access from root.

/// Resolve a user-entered path to be relative to the compilation
/// environment's root.
pub fn locate(&self, path: &str) -> StrResult<PathBuf> {
    if !self.location.is_detached() {
        if let Some(path) = path.strip_prefix('/') {
            return Ok(self.world().root().join(path).normalize());
        }

        if let Some(dir) = self.world().source(self.location).path().parent() {
            return Ok(dir.join(path).normalize());
        }
    }

    Err("cannot access file system from here".into())
}

I am of the opinion that global/absolute paths should not be allowed into Typst. Absolute paths are simple to reason with, but completely against the spirit of collaboration.

• Windows and Linux use different conventions for absolute paths, so your code will not compile on a different OS
• typst.app is entirely browser based, so your code will not compile on it
• If you move/rename a parent folder, your code will not compile.

If you have the burning need to import with absolute paths, I would suggest implementing something similar to PYTHONPATH, which lets you define an absolute path from which modules are searched.

I see reasonable use in personal projects ran locally (perhaps, sharing paper.typ for all research-papers in different directories), but I can see your point. While I deem // as a good solution (with appropriate documentation), your suggestion with TYPSTPATH would also be ok.

TYPSTPATH seems good as it will behave same as ~/texmf for LaTeX.

Absolute paths are not good and using relative path with many ../ is little confusing. Alternative would be to use symbolic links but I am not sure if Windows supports it.

Another way to do it could be command-line arguments, kind of like how cc does include-paths. This would also allow multiple directories to look in. typst -I /home/foo -I ~/macros

Adding a command line option to specify the import path like @ollelogdahl suggested would also make it possible to keep a united template and use this on multiple documents without adjusting the import path in every document.

As a teacher i create lot's of worksheets based on the same template but have the files structured in different folders. So i could keep #import "templates/worsheet.typ":* on every document and specify the template path in the cli depending on which system i currently work.

I am of the opinion that global/absolute paths should not be allowed into Typst.

I think there are valid use-cases for absolute paths. I'm currently using typst on a web server to generate multiple PDF's. Allowing only relative paths would force me to constantly copy images over to the relative directory whereas an absolute path is way easier to manage and saves some copying. Also, limiting capabilities in order to ensure "correct" behavior is almost always a mistake if you ask me.

limiting capabilities in order to ensure "correct" behavior is almost always a mistake if you ask me.

Could you explain why mainstream languages (eg. Python) do not allow importing by absolute path?

I think the answer is a combination of two things:

1. Portability: Absolute paths are specific to a particular file system structure and operating system
2. Maintainability: Modules encourage developers to create tree-shaped packages with self-contained and reusable components.

As experienced programmers/early adopters, we know the merits/flaws of absolute and relative paths. It is ovbious to us to avoid circular imports. It is ovbious to us to avoid absolute paths in cross-platform scripts.

It is not ovbious to inexperienced programmers. I've seen students struggle to access C:\Users\UserName\Downloads on their Macbook. Many people have never heard of a relative path.

If you want Typst to be widely used, these are the people you must consider.

I'm currently using typst on a web server to generate multiple PDF's.

I don't see how your use case is not covered by TYPSTPATH or typst -I /home/foo -I ~/macros.

This is a solution that is perhaps marginally inconvenient to you, but I hope you recognise that 99% of Typst users will never experience this inconvenience. They will certainly trip up with when using absolute paths.

I just ran into this issue when trying to create a new local file using my BibTex bibliography file which I store in one place in my folder tree. I understand all the issues around allowing absolute file paths with collaboration, security, etc... but I'm just trying to write a syllabus for a class and I want to include my personal bibliography file. I trust myself, and no-one else is ever going to edit this file. It would vastly simplify my user experience if I could just enter the absolute path of the .bib file. I would even be ok if to write absolute paths you had to do something like: #bibliography(Path('/home/willis/bibliography.bib', absolute=true)) to make it clear that you would going outside of intended behavior.

@willismonroe Absolute paths are resolved relative to the project root, which is by default the folder where the main Typst file resides in. However, you can adjust it. For instance typst compile --root / file.typ would turn your whole disk into the project and as such, every absolute path would start from the disk root. Relative paths would continue to work as usual. You can also use /home/willis as your root or do something like --root ... Another alternative would be to turn your bibliography into a local package and use it without touching the project root.

I'm going to close this as there are different options to achieve this with --root and packages.