Clarify the path argument of the image element (#4892)

Co-authored-by: Laurenz <laurmaedje@gmail.com>
Co-authored-by: Martin Haug <mhaug@live.de>

10 files changed, 65 insertions, 1 deletions

diff --git a/crates/typst/src/foundations/plugin.rs b/crates/typst/src/foundations/plugin.rs
index 57dea827..4dc03014 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<EcoString>,
     ) -> SourceResult<Plugin> {
         let Spanned { v: path, span } = path;
diff --git a/crates/typst/src/loading/cbor.rs b/crates/typst/src/loading/cbor.rs
index bce09271..e2d0f7c7 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<EcoString>,
 ) -> SourceResult<Value> {
     let Spanned { v: path, span } = path;
diff --git a/crates/typst/src/loading/csv.rs b/crates/typst/src/loading/csv.rs
index 4548bbd7..62a9bf69 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<EcoString>,
     /// 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 8e829594..d466d043 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<EcoString>,
 ) -> SourceResult<Value> {
     let Spanned { v: path, span } = path;
diff --git a/crates/typst/src/loading/read.rs b/crates/typst/src/loading/read.rs
index ff7f6b43..3bec9bd7 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<EcoString>,
     /// The encoding to read the file with.
     ///
diff --git a/crates/typst/src/loading/toml.rs b/crates/typst/src/loading/toml.rs
index 6884e6fe..17ab6b53 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<EcoString>,
 ) -> SourceResult<Value> {
     let Spanned { v: path, span } = path;
diff --git a/crates/typst/src/loading/xml.rs b/crates/typst/src/loading/xml.rs
index 1c494e78..fefb63c2 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<EcoString>,
 ) -> SourceResult<Value> {
     let Spanned { v: path, span } = path;
diff --git a/crates/typst/src/loading/yaml.rs b/crates/typst/src/loading/yaml.rs
index d578eda4..22311cf6 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<EcoString>,
 ) -> SourceResult<Value> {
     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 d267ca04..aeebb471 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 aac1cad8..fdc4d154 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.