More package documentation

docs/src/html.rs

@@ -293,6 +293,7 @@ impl<'a> Handler<'a> {
             "$type" => "/docs/reference/types/",
             "$func" => "/docs/reference/",
             "$guides" => "/docs/guides/",
+            "$packages" => "/docs/packages/",
             "$changelog" => "/docs/changelog/",
             "$community" => "/docs/community/",
             _ => panic!("unknown link root: {root}"),

docs/src/lib.rs

@@ -57,7 +57,7 @@ pub fn provide(resolver: &dyn Resolver) -> Vec<PageModel> {
         tutorial_pages(resolver),
         reference_pages(resolver),
         guides_pages(resolver),
-        packages_page(),
+        packages_page(resolver),
         markdown_page(resolver, "/docs/", "general/changelog.md"),
         markdown_page(resolver, "/docs/", "general/community.md"),
     ]
@@ -119,7 +119,7 @@ pub enum BodyModel {
     Funcs(FuncsModel),
     Type(TypeModel),
     Symbols(SymbolsModel),
-    Packages,
+    Packages(Html),
 }
 
 /// Build the tutorial.
@@ -167,14 +167,14 @@ fn guides_pages(resolver: &dyn Resolver) -> PageModel {
 }
 
 /// Build the packages section.
-fn packages_page() -> PageModel {
+fn packages_page(resolver: &dyn Resolver) -> PageModel {
     PageModel {
         route: "/docs/packages/".into(),
         title: "Packages".into(),
         description: "Packages for Typst.".into(),
         part: None,
         outline: vec![],
-        body: BodyModel::Packages,
+        body: BodyModel::Packages(Html::markdown(resolver, details("packages"))),
         children: vec![],
     }
 }

docs/src/reference/details.yml

@@ -164,3 +164,11 @@ data-loading: |
 
 utility: |
   Useful utility functions.
+
+packages: |
+  Typst [packages]($scripting/#packages) encapsulate reusable building blocks
+  and make them reusable across projects. Below is a list of Typst packages
+  created by the community. Due to the early and experimental nature of Typst's
+  package management, they all live in a `preview` namespace. Click on a
+  package's name to view its documentation and use the copy button on the right
+  to get a full import statement for it.

docs/src/reference/scripting.md

@@ -294,6 +294,25 @@ the following example:
 #face.grin
 ```
 
+## Packages { #packages }
+To reuse building blocks across projects, you can also create and import Typst
+_packages._ A package import is specified as a triple of a namespace, a name,
+and a version.
+
+```example
+>>> #let add(x, y) = x + y
+<<< #import "@preview/example:0.1.0": add
+#add(2, 7)
+```
+
+The `preview` namespace contains packages shared by the community. You can find
+a searchable list of available community packages in the [packages]($packages)
+section.
+
+If you are using Typst locally, you can also create your own system-local
+packages. For more details on this, see the
+[package repository](https://github.com/typst/packages).
+
 ## Operators { #operators }
 The following table lists all available unary and binary operators with effect,
 arity (unary, binary) and precedence level (higher binds stronger).
@@ -322,3 +341,5 @@ arity (unary, binary) and precedence level (higher binds stronger).
 |  `{-=}`    | Subtraction-Assignment          | Binary |     1      |
 |  `{*=}`    | Multiplication-Assignment       | Binary |     1      |
 |  `{/=}`    | Division-Assignment             | Binary |     1      |
+
+[semver]: https://semver.org/