From cf35c2f44c6fdd8d6ef6f5df81f144db7355286d Mon Sep 17 00:00:00 2001 From: Dmytro Kravchenko-Loznia <32360199+kravchenkoloznia@users.noreply.github.com> Date: Thu, 26 Sep 2024 16:07:39 +0200 Subject: [PATCH] Clarify the path argument of the image element (#4892) Co-authored-by: Laurenz Co-authored-by: Martin Haug --- crates/typst/src/foundations/plugin.rs | 2 ++ crates/typst/src/loading/cbor.rs | 2 ++ crates/typst/src/loading/csv.rs | 2 ++ crates/typst/src/loading/json.rs | 2 ++ crates/typst/src/loading/read.rs | 2 ++ crates/typst/src/loading/toml.rs | 2 ++ crates/typst/src/loading/xml.rs | 2 ++ crates/typst/src/loading/yaml.rs | 2 ++ crates/typst/src/visualize/image/mod.rs | 4 ++- docs/reference/syntax.md | 46 +++++++++++++++++++++++++ 10 files changed, 65 insertions(+), 1 deletion(-) diff --git a/crates/typst/src/foundations/plugin.rs b/crates/typst/src/foundations/plugin.rs index 57dea827e..4dc03014a 100644 --- a/crates/typst/src/foundations/plugin.rs +++ b/crates/typst/src/foundations/plugin.rs @@ -155,6 +155,8 @@ impl Plugin { /// The engine. engine: &mut Engine, /// Path to a WebAssembly file. + /// + /// For more details, see the [Paths section]($syntax/#paths). path: Spanned, ) -> SourceResult { let Spanned { v: path, span } = path; diff --git a/crates/typst/src/loading/cbor.rs b/crates/typst/src/loading/cbor.rs index bce092712..e2d0f7c73 100644 --- a/crates/typst/src/loading/cbor.rs +++ b/crates/typst/src/loading/cbor.rs @@ -22,6 +22,8 @@ pub fn cbor( /// The engine. engine: &mut Engine, /// Path to a CBOR file. + /// + /// For more details, see the [Paths section]($syntax/#paths). path: Spanned, ) -> SourceResult { let Spanned { v: path, span } = path; diff --git a/crates/typst/src/loading/csv.rs b/crates/typst/src/loading/csv.rs index 4548bbd7b..62a9bf699 100644 --- a/crates/typst/src/loading/csv.rs +++ b/crates/typst/src/loading/csv.rs @@ -29,6 +29,8 @@ pub fn csv( /// The engine. engine: &mut Engine, /// Path to a CSV file. + /// + /// For more details, see the [Paths section]($syntax/#paths). path: Spanned, /// The delimiter that separates columns in the CSV file. /// Must be a single ASCII character. diff --git a/crates/typst/src/loading/json.rs b/crates/typst/src/loading/json.rs index 8e829594b..d466d0437 100644 --- a/crates/typst/src/loading/json.rs +++ b/crates/typst/src/loading/json.rs @@ -54,6 +54,8 @@ pub fn json( /// The engine. engine: &mut Engine, /// Path to a JSON file. + /// + /// For more details, see the [Paths section]($syntax/#paths). path: Spanned, ) -> SourceResult { let Spanned { v: path, span } = path; diff --git a/crates/typst/src/loading/read.rs b/crates/typst/src/loading/read.rs index ff7f6b436..3bec9bd7b 100644 --- a/crates/typst/src/loading/read.rs +++ b/crates/typst/src/loading/read.rs @@ -27,6 +27,8 @@ pub fn read( /// The engine. engine: &mut Engine, /// Path to a file. + /// + /// For more details, see the [Paths section]($syntax/#paths). path: Spanned, /// The encoding to read the file with. /// diff --git a/crates/typst/src/loading/toml.rs b/crates/typst/src/loading/toml.rs index 6884e6fe3..17ab6b536 100644 --- a/crates/typst/src/loading/toml.rs +++ b/crates/typst/src/loading/toml.rs @@ -32,6 +32,8 @@ pub fn toml( /// The engine. engine: &mut Engine, /// Path to a TOML file. + /// + /// For more details, see the [Paths section]($syntax/#paths). path: Spanned, ) -> SourceResult { let Spanned { v: path, span } = path; diff --git a/crates/typst/src/loading/xml.rs b/crates/typst/src/loading/xml.rs index 1c494e788..fefb63c2b 100644 --- a/crates/typst/src/loading/xml.rs +++ b/crates/typst/src/loading/xml.rs @@ -61,6 +61,8 @@ pub fn xml( /// The engine. engine: &mut Engine, /// Path to an XML file. + /// + /// For more details, see the [Paths section]($syntax/#paths). path: Spanned, ) -> SourceResult { let Spanned { v: path, span } = path; diff --git a/crates/typst/src/loading/yaml.rs b/crates/typst/src/loading/yaml.rs index d578eda4c..22311cf66 100644 --- a/crates/typst/src/loading/yaml.rs +++ b/crates/typst/src/loading/yaml.rs @@ -44,6 +44,8 @@ pub fn yaml( /// The engine. engine: &mut Engine, /// Path to a YAML file. + /// + /// For more details, see the [Paths section]($syntax/#paths). path: Spanned, ) -> SourceResult { let Spanned { v: path, span } = path; diff --git a/crates/typst/src/visualize/image/mod.rs b/crates/typst/src/visualize/image/mod.rs index d267ca044..aeebb4716 100644 --- a/crates/typst/src/visualize/image/mod.rs +++ b/crates/typst/src/visualize/image/mod.rs @@ -54,7 +54,9 @@ use crate::World; /// [gh-svg]: https://github.com/typst/typst/issues?q=is%3Aopen+is%3Aissue+label%3Asvg #[elem(scope, Show, LocalName, Figurable)] pub struct ImageElem { - /// Path to an image file. + /// Path to an image file + /// + /// For more details, see the [Paths section]($syntax/#paths). #[required] #[parse( let Spanned { v: path, span } = diff --git a/docs/reference/syntax.md b/docs/reference/syntax.md index aac1cad8d..fdc4d154a 100644 --- a/docs/reference/syntax.md +++ b/docs/reference/syntax.md @@ -167,3 +167,49 @@ sequence: `[\u{1f600}]`. The same kind of escape sequences also work in I got an ice cream for \$1.50! \u{1f600} ``` + +## Paths +Typst has various features that require a file path to reference external +resources such as images, Typst files, or data files. Paths are represented as +[strings]($str). There are two kinds of paths: Relative and absolute. + +- A **relative path** searches from the location of the Typst file where the + feature is invoked. It is the default: + ```typ + #image("images/logo.png") + ``` + +- An **absolute path** searches from the _root_ of the project. It starts with a + leading `/`: + ```typ + #image("/assets/logo.png") + ``` + +### Project root +By default, the project root is the parent directory of the main Typst file. +For security reasons, you cannot read any files outside of the root directory. + +If you want to set a specific folder as the root of your project, you can use +the CLI's `--root` flag. Make sure that the main file is contained in the +folder's subtree! +```bash +typst compile --root .. file.typ +``` + +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). + +### Paths and packages +A package can only load files from its own directory. Within it, absolute paths +point to the package root, rather than the project root. For this reason, it +cannot directly load files from the project directory. If a package needs +resources from the project (such as a logo image), you must pass the already +loaded image, e.g. as a named parameter `{logo: image("mylogo.svg")}`. Note that +you can then still customize the image's appearance with a set rule within the +package. + +In the future, paths might become a +[distinct type from strings](https://github.com/typst/typst/issues/971), so that +they can retain knowledge of where they were constructed. This way, resources +could be loaded from a different root.