typst: add initial support for typst packages (#369283)

3 files changed, 81 insertions, 0 deletions

diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md
index 12e54e2a76ab..2624b9afc5e4 100644
--- a/doc/languages-frameworks/index.md
+++ b/doc/languages-frameworks/index.md
@@ -98,6 +98,7 @@ scheme.section.md
 swift.section.md
 tcl.section.md
 texlive.section.md
+typst.section.md
 vim.section.md
 neovim.section.md
 ```
diff --git a/doc/languages-frameworks/typst.section.md b/doc/languages-frameworks/typst.section.md
new file mode 100644
index 000000000000..1e025be04cc7
--- /dev/null
+++ b/doc/languages-frameworks/typst.section.md
@@ -0,0 +1,62 @@
+# Typst {#typst}
+
+Typst can be configured to include packages from [Typst Universe](https://typst.app/universe/) or custom packages.
+
+## Custom Environment {#typst-custom-environment}
+
+You can create a custom Typst environment with a selected set of packages from **Typst Universe** using the following code. It is also possible to specify a Typst package with a specific version (e.g., `cetz_0_3_0`). A package without a version number will always refer to its latest version.
+
+```nix
+typst.withPackages (p: with p; [
+  polylux_0_4_0
+  cetz_0_3_0
+])
+```
+
+### Handling Outdated Package Hashes {#typst-handling-outdated-package-hashes}
+
+Since **Typst Universe** does not provide a way to fetch a package with a specific hash, the package hashes in `nixpkgs` can sometimes be outdated. To resolve this issue, you can manually override the package source using the following approach:
+
+```nix
+typst.withPackages.override (old: {
+  typstPackages = old.typstPackages.extend (_: previous: {
+    polylux_0_4_0 = previous.polylux_0_4_0.overrideAttrs (oldPolylux: {
+      src = oldPolylux.src.overrideAttrs {
+        outputHash = YourUpToDatePolyluxHash;
+      };
+    });
+  });
+}) (p: with p; [
+  polylux_0_4_0
+  cetz_0_3_0
+])
+```
+
+## Custom Packages {#typst-custom-packages}
+
+`Nixpkgs` provides a helper function, `buildTypstPackage`, to build custom Typst packages that can be used within the Typst environment. However, all dependencies of the custom package must be explicitly specified in `typstDeps`.
+
+Here's how to define a custom Typst package:
+
+```nix
+{ buildTypstPackage, typstPackages, fetchzip }:
+
+buildTypstPackage (finalAttrs: {
+  pname = "my-typst-package";
+  version = "0.0.1";
+  src = fetchzip { ... };
+  typstDeps = with typstPackages; [ cetz_0_3_0 ];
+})
+```
+
+### Package Scope and Usage {#typst-package-scope-and-usage}
+
+By default, every custom package is scoped under `@preview`, as shown below:
+
+```typst
+#import "@preview/my-typst-package:0.0.1": *
+```
+
+Since `@preview` is intended for packages from **Typst Universe**, it is recommended to use this approach **only for temporary or experimental modifications over existing packages** from **Typst Universe**.
+
+On the other hand, **local packages**, packages scoped under `@local`, are **not** considered part of the Typst environment. This means that local packages must be manually linked to the Typst compiler if needed.
diff --git a/doc/redirects.json b/doc/redirects.json
index 4925709c92c6..46eb54c6c67b 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -413,6 +413,24 @@
   "tester-testEqualArrayOrMap-return": [
     "index.html#tester-testEqualArrayOrMap-return"
   ],
+  "typst": [
+    "index.html#typst",
+    "doc/languages-frameworks/typst.section.md#typst"
+  ],
+  "typst-custom-environment": [
+    "index.html#typst-custom-environment",
+    "doc/languages-frameworks/typst.section.md#typst-custom-environment"
+  ],
+  "typst-custom-packages": [
+    "index.html#typst-custom-packages",
+    "doc/languages-frameworks/typst.section.md#typst-custom-packages"
+  ],
+  "typst-handling-outdated-package-hashes": [
+    "index.html#typst-handling-outdated-package-hashes"
+  ],
+  "typst-package-scope-and-usage": [
+    "index.html#typst-package-scope-and-usage"
+  ],
   "variables-specifying-dependencies": [
     "index.html#variables-specifying-dependencies"
   ],