Export target docs (#5812)

Co-authored-by: Martin Haug <3874949+reknih@users.noreply.github.com>

24 files changed, 172 insertions, 374 deletions

diff --git a/crates/typst-library/src/foundations/mod.rs b/crates/typst-library/src/foundations/mod.rs
index c335484f..8e3aa060 100644
--- a/crates/typst-library/src/foundations/mod.rs
+++ b/crates/typst-library/src/foundations/mod.rs
@@ -85,16 +85,9 @@ use crate::engine::Engine;
 use crate::routines::EvalMode;
 use crate::{Feature, Features};
 
-/// Foundational types and functions.
-///
-/// Here, you'll find documentation for basic data types like [integers]($int)
-/// and [strings]($str) as well as details about core computational functions.
-#[category]
-pub static FOUNDATIONS: Category;
-
 /// Hook up all `foundations` definitions.
 pub(super) fn define(global: &mut Scope, inputs: Dict, features: &Features) {
-    global.start_category(FOUNDATIONS);
+    global.start_category(crate::Category::Foundations);
     global.define_type::<bool>();
     global.define_type::<i64>();
     global.define_type::<f64>();
@@ -125,6 +118,7 @@ pub(super) fn define(global: &mut Scope, inputs: Dict, features: &Features) {
     }
     global.define("calc", calc::module());
     global.define("sys", sys::module(inputs));
+    global.reset_category();
 }
 
 /// Fails with an error.
diff --git a/crates/typst-library/src/foundations/scope.rs b/crates/typst-library/src/foundations/scope.rs
index d6c5a8d0..e1ce61b8 100644
--- a/crates/typst-library/src/foundations/scope.rs
+++ b/crates/typst-library/src/foundations/scope.rs
@@ -1,6 +1,3 @@
-#[doc(inline)]
-pub use typst_macros::category;
-
 use std::fmt::{self, Debug, Formatter};
 use std::hash::{Hash, Hasher};
 
@@ -8,14 +5,13 @@ use ecow::{eco_format, EcoString};
 use indexmap::map::Entry;
 use indexmap::IndexMap;
 use typst_syntax::Span;
-use typst_utils::Static;
 
 use crate::diag::{bail, DeprecationSink, HintedStrResult, HintedString, StrResult};
 use crate::foundations::{
     Element, Func, IntoValue, NativeElement, NativeFunc, NativeFuncData, NativeType,
     Type, Value,
 };
-use crate::Library;
+use crate::{Category, Library};
 
 /// A stack of scopes.
 #[derive(Debug, Default, Clone)]
@@ -361,46 +357,6 @@ pub enum Capturer {
     Context,
 }
 
-/// A group of related definitions.
-#[derive(Copy, Clone, Eq, PartialEq, Hash)]
-pub struct Category(Static<CategoryData>);
-
-impl Category {
-    /// Create a new category from raw data.
-    pub const fn from_data(data: &'static CategoryData) -> Self {
-        Self(Static(data))
-    }
-
-    /// The category's name.
-    pub fn name(&self) -> &'static str {
-        self.0.name
-    }
-
-    /// The type's title case name, for use in documentation (e.g. `String`).
-    pub fn title(&self) -> &'static str {
-        self.0.title
-    }
-
-    /// Documentation for the category.
-    pub fn docs(&self) -> &'static str {
-        self.0.docs
-    }
-}
-
-impl Debug for Category {
-    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
-        write!(f, "Category({})", self.name())
-    }
-}
-
-/// Defines a category.
-#[derive(Debug)]
-pub struct CategoryData {
-    pub name: &'static str,
-    pub title: &'static str,
-    pub docs: &'static str,
-}
-
 /// The error message when trying to mutate a variable from the standard
 /// library.
 #[cold]
diff --git a/crates/typst-library/src/foundations/target.rs b/crates/typst-library/src/foundations/target.rs
index 5841552e..2a21fd42 100644
--- a/crates/typst-library/src/foundations/target.rs
+++ b/crates/typst-library/src/foundations/target.rs
@@ -3,7 +3,7 @@ use comemo::Tracked;
 use crate::diag::HintedStrResult;
 use crate::foundations::{elem, func, Cast, Context};
 
-/// The compilation target.
+/// The export target.
 #[derive(Debug, Default, Copy, Clone, PartialEq, Hash, Cast)]
 pub enum Target {
     /// The target that is used for paged, fully laid-out content.
@@ -28,7 +28,49 @@ pub struct TargetElem {
     pub target: Target,
 }
 
-/// Returns the current compilation target.
+/// Returns the current export target.
+///
+/// This function returns either
+/// - `{"paged"}` (for PDF, PNG, and SVG export), or
+/// - `{"html"}` (for HTML export).
+///
+/// The design of this function is not yet finalized and for this reason it is
+/// guarded behind the `html` feature. Visit the [HTML documentation
+/// page]($html) for more details.
+///
+/// # When to use it
+/// This function allows you to format your document properly across both HTML
+/// and paged export targets. It should primarily be used in templates and show
+/// rules, rather than directly in content. This way, the document's contents
+/// can be fully agnostic to the export target and content can be shared between
+/// PDF and HTML export.
+///
+/// # Varying targets
+/// This function is [contextual]($context) as the target can vary within a
+/// single compilation: When exporting to HTML, the target will be `{"paged"}`
+/// while within an [`html.frame`].
+///
+/// # Example
+/// ```example
+/// #let kbd(it) = context {
+///   if target() == "html" {
+///     html.elem("kbd", it)
+///   } else {
+///     set text(fill: rgb("#1f2328"))
+///     let r = 3pt
+///     box(
+///       fill: rgb("#f6f8fa"),
+///       stroke: rgb("#d1d9e0b3"),
+///       outset: (y: r),
+///       inset: (x: r),
+///       radius: r,
+///       raw(it)
+///     )
+///   }
+/// }
+///
+/// Press #kbd("F1") for help.
+/// ```
 #[func(contextual)]
 pub fn target(context: Tracked<Context>) -> HintedStrResult<Target> {
     Ok(TargetElem::target_in(context.styles()?))
diff --git a/crates/typst-library/src/html/mod.rs b/crates/typst-library/src/html/mod.rs
index c412b460..1d88781c 100644
--- a/crates/typst-library/src/html/mod.rs
+++ b/crates/typst-library/src/html/mod.rs
@@ -6,53 +6,77 @@ pub use self::dom::*;
 
 use ecow::EcoString;
 
-use crate::foundations::{category, elem, Category, Content, Module, Scope};
-
-/// HTML output.
-#[category]
-pub static HTML: Category;
+use crate::foundations::{elem, Content, Module, Scope};
 
 /// Create a module with all HTML definitions.
 pub fn module() -> Module {
     let mut html = Scope::deduplicating();
-    html.start_category(HTML);
+    html.start_category(crate::Category::Html);
     html.define_elem::<HtmlElem>();
     html.define_elem::<FrameElem>();
     Module::new("html", html)
 }
 
-/// A HTML element that can contain Typst content.
+/// An HTML element that can contain Typst content.
+///
+/// Typst's HTML export automatically generates the appropriate tags for most
+/// elements. However, sometimes, it is desirable to retain more control. For
+/// example, when using Typst to generate your blog, you could use this function
+/// to wrap each article in an `<article>` tag.
+///
+/// Typst is aware of what is valid HTML. A tag and its attributes must form
+/// syntactically valid HTML. Some tags, like `meta` do not accept content.
+/// Hence, you must not provide a body for them. We may add more checks in the
+/// future, so be sure that you are generating valid HTML when using this
+/// function.
+///
+/// Normally, Typst will generate `html`, `head`, and `body` tags for you. If
+/// you instead create them with this function, Typst will omit its own tags.
+///
+/// ```typ
+/// #html.elem("div", attrs: (style: "background: aqua"))[
+///   A div with _Typst content_ inside!
+/// ]
+/// ```
 #[elem(name = "elem")]
 pub struct HtmlElem {
     /// The element's tag.
     #[required]
     pub tag: HtmlTag,
 
-    /// The element's attributes.
+    /// The element's HTML attributes.
     #[borrowed]
     pub attrs: HtmlAttrs,
 
     /// The contents of the HTML element.
+    ///
+    /// The body can be arbitrary Typst content.
     #[positional]
     #[borrowed]
     pub body: Option<Content>,
 }
 
 impl HtmlElem {
-    /// Add an atribute to the element.
+    /// Add an attribute to the element.
     pub fn with_attr(mut self, attr: HtmlAttr, value: impl Into<EcoString>) -> Self {
         self.attrs.get_or_insert_with(Default::default).push(attr, value);
         self
     }
 }
 
-/// An element that forces its contents to be laid out.
+/// An element that lays out its content as an inline SVG.
+///
+/// Sometimes, converting Typst content to HTML is not desirable. This can be
+/// the case for plots and other content that relies on positioning and styling
+/// to convey its message.
 ///
-/// Integrates content that requires layout (e.g. a plot) into HTML output
-/// by turning it into an inline SVG.
+/// This function allows you to use the Typst layout engine that would also be
+/// used for PDF, SVG, and PNG export to render a part of your document exactly
+/// how it would appear when exported in one of these formats. It embeds the
+/// content as an inline SVG.
 #[elem]
 pub struct FrameElem {
-    /// The contents that shall be laid out.
+    /// The content that shall be laid out.
     #[positional]
     #[required]
     pub body: Content,
diff --git a/crates/typst-library/src/introspection/mod.rs b/crates/typst-library/src/introspection/mod.rs
index d8184330..995fbd7b 100644
--- a/crates/typst-library/src/introspection/mod.rs
+++ b/crates/typst-library/src/introspection/mod.rs
@@ -25,24 +25,11 @@ pub use self::query_::*;
 pub use self::state::*;
 pub use self::tag::*;
 
-use crate::foundations::{category, Category, Scope};
-
-/// Interactions between document parts.
-///
-/// This category is home to Typst's introspection capabilities: With the
-/// `counter` function, you can access and manipulate page, section, figure, and
-/// equation counters or create custom ones. Meanwhile, the `query` function
-/// lets you search for elements in the document to construct things like a list
-/// of figures or headers which show the current chapter title.
-///
-/// Most of the functions are _contextual._ It is recommended to read the chapter
-/// on [context] before continuing here.
-#[category]
-pub static INTROSPECTION: Category;
+use crate::foundations::Scope;
 
 /// Hook up all `introspection` definitions.
 pub fn define(global: &mut Scope) {
-    global.start_category(INTROSPECTION);
+    global.start_category(crate::Category::Introspection);
     global.define_type::<Location>();
     global.define_type::<Counter>();
     global.define_type::<State>();
@@ -50,4 +37,5 @@ pub fn define(global: &mut Scope) {
     global.define_func::<here>();
     global.define_func::<query>();
     global.define_func::<locate>();
+    global.reset_category();
 }
diff --git a/crates/typst-library/src/layout/mod.rs b/crates/typst-library/src/layout/mod.rs
index 57518fe7..ef1ecdb3 100644
--- a/crates/typst-library/src/layout/mod.rs
+++ b/crates/typst-library/src/layout/mod.rs
@@ -64,17 +64,11 @@ pub use self::spacing::*;
 pub use self::stack::*;
 pub use self::transform::*;
 
-use crate::foundations::{category, Category, Scope};
-
-/// Arranging elements on the page in different ways.
-///
-/// By combining layout functions, you can create complex and automatic layouts.
-#[category]
-pub static LAYOUT: Category;
+use crate::foundations::Scope;
 
 /// Hook up all `layout` definitions.
 pub fn define(global: &mut Scope) {
-    global.start_category(LAYOUT);
+    global.start_category(crate::Category::Layout);
     global.define_type::<Length>();
     global.define_type::<Angle>();
     global.define_type::<Ratio>();
@@ -103,4 +97,5 @@ pub fn define(global: &mut Scope) {
     global.define_elem::<HideElem>();
     global.define_func::<measure>();
     global.define_func::<layout>();
+    global.reset_category();
 }
diff --git a/crates/typst-library/src/lib.rs b/crates/typst-library/src/lib.rs
index 460321aa..c39024f7 100644
--- a/crates/typst-library/src/lib.rs
+++ b/crates/typst-library/src/lib.rs
@@ -29,6 +29,7 @@ pub mod visualize;
 
 use std::ops::{Deref, Range};
 
+use serde::{Deserialize, Serialize};
 use typst_syntax::{FileId, Source, Span};
 use typst_utils::{LazyHash, SmallBitSet};
 
@@ -236,31 +237,72 @@ pub enum Feature {
     Html,
 }
 
+/// A group of related standard library definitions.
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Category {
+    Foundations,
+    Introspection,
+    Layout,
+    DataLoading,
+    Math,
+    Model,
+    Symbols,
+    Text,
+    Visualize,
+    Pdf,
+    Html,
+    Svg,
+    Png,
+}
+
+impl Category {
+    /// The kebab-case name of the category.
+    pub fn name(&self) -> &'static str {
+        match self {
+            Self::Foundations => "foundations",
+            Self::Introspection => "introspection",
+            Self::Layout => "layout",
+            Self::DataLoading => "data-loading",
+            Self::Math => "math",
+            Self::Model => "model",
+            Self::Symbols => "symbols",
+            Self::Text => "text",
+            Self::Visualize => "visualize",
+            Self::Pdf => "pdf",
+            Self::Html => "html",
+            Self::Svg => "svg",
+            Self::Png => "png",
+        }
+    }
+}
+
 /// Construct the module with global definitions.
 fn global(math: Module, inputs: Dict, features: &Features) -> Module {
     let mut global = Scope::deduplicating();
+
     self::foundations::define(&mut global, inputs, features);
     self::model::define(&mut global);
     self::text::define(&mut global);
-    global.reset_category();
-    global.define("math", math);
     self::layout::define(&mut global);
     self::visualize::define(&mut global);
     self::introspection::define(&mut global);
     self::loading::define(&mut global);
     self::symbols::define(&mut global);
-    self::pdf::define(&mut global);
-    global.reset_category();
+
+    global.define("math", math);
+    global.define("pdf", self::pdf::module());
     if features.is_enabled(Feature::Html) {
         global.define("html", self::html::module());
     }
+
     prelude(&mut global);
+
     Module::new("global", global)
 }
 
 /// Defines scoped values that are globally available, too.
 fn prelude(global: &mut Scope) {
-    global.reset_category();
     global.define("black", Color::BLACK);
     global.define("gray", Color::GRAY);
     global.define("silver", Color::SILVER);
diff --git a/crates/typst-library/src/loading/cbor.rs b/crates/typst-library/src/loading/cbor.rs
index bd65e844..801ca617 100644
--- a/crates/typst-library/src/loading/cbor.rs
+++ b/crates/typst-library/src/loading/cbor.rs
@@ -34,9 +34,6 @@ pub fn cbor(
 #[scope]
 impl cbor {
     /// Reads structured data from CBOR bytes.
-    ///
-    /// This function is deprecated. The [`cbor`] function now accepts bytes
-    /// directly.
     #[func(title = "Decode CBOR")]
     #[deprecated = "`cbor.decode` is deprecated, directly pass bytes to `cbor` instead"]
     pub fn decode(
diff --git a/crates/typst-library/src/loading/csv.rs b/crates/typst-library/src/loading/csv.rs
index d01d687b..6fdec445 100644
--- a/crates/typst-library/src/loading/csv.rs
+++ b/crates/typst-library/src/loading/csv.rs
@@ -96,9 +96,6 @@ pub fn csv(
 #[scope]
 impl csv {
     /// Reads structured data from a CSV string/bytes.
-    ///
-    /// This function is deprecated. The [`csv`] function now accepts bytes
-    /// directly.
     #[func(title = "Decode CSV")]
     #[deprecated = "`csv.decode` is deprecated, directly pass bytes to `csv` instead"]
     pub fn decode(
diff --git a/crates/typst-library/src/loading/json.rs b/crates/typst-library/src/loading/json.rs
index 52c87371..185bac14 100644
--- a/crates/typst-library/src/loading/json.rs
+++ b/crates/typst-library/src/loading/json.rs
@@ -65,9 +65,6 @@ pub fn json(
 #[scope]
 impl json {
     /// Reads structured data from a JSON string/bytes.
-    ///
-    /// This function is deprecated. The [`json`] function now accepts bytes
-    /// directly.
     #[func(title = "Decode JSON")]
     #[deprecated = "`json.decode` is deprecated, directly pass bytes to `json` instead"]
     pub fn decode(
diff --git a/crates/typst-library/src/loading/mod.rs b/crates/typst-library/src/loading/mod.rs
index c645b691..c57e0288 100644
--- a/crates/typst-library/src/loading/mod.rs
+++ b/crates/typst-library/src/loading/mod.rs
@@ -29,19 +29,12 @@ pub use self::yaml_::*;
 
 use crate::diag::{At, SourceResult};
 use crate::foundations::OneOrMultiple;
-use crate::foundations::{cast, category, Bytes, Category, Scope, Str};
+use crate::foundations::{cast, Bytes, Scope, Str};
 use crate::World;
 
-/// Data loading from external files.
-///
-/// These functions help you with loading and embedding data, for example from
-/// the results of an experiment.
-#[category]
-pub static DATA_LOADING: Category;
-
 /// Hook up all `data-loading` definitions.
 pub(super) fn define(global: &mut Scope) {
-    global.start_category(DATA_LOADING);
+    global.start_category(crate::Category::DataLoading);
     global.define_func::<read>();
     global.define_func::<csv>();
     global.define_func::<json>();
@@ -49,6 +42,7 @@ pub(super) fn define(global: &mut Scope) {
     global.define_func::<yaml>();
     global.define_func::<cbor>();
     global.define_func::<xml>();
+    global.reset_category();
 }
 
 /// Something we can retrieve byte data from.
diff --git a/crates/typst-library/src/loading/toml.rs b/crates/typst-library/src/loading/toml.rs
index 45611246..2660e7e7 100644
--- a/crates/typst-library/src/loading/toml.rs
+++ b/crates/typst-library/src/loading/toml.rs
@@ -44,9 +44,6 @@ pub fn toml(
 #[scope]
 impl toml {
     /// Reads structured data from a TOML string/bytes.
-    ///
-    /// This function is deprecated. The [`toml`] function now accepts bytes
-    /// directly.
     #[func(title = "Decode TOML")]
     #[deprecated = "`toml.decode` is deprecated, directly pass bytes to `toml` instead"]
     pub fn decode(
diff --git a/crates/typst-library/src/loading/xml.rs b/crates/typst-library/src/loading/xml.rs
index 0172071b..32ed6f24 100644
--- a/crates/typst-library/src/loading/xml.rs
+++ b/crates/typst-library/src/loading/xml.rs
@@ -77,9 +77,6 @@ pub fn xml(
 #[scope]
 impl xml {
     /// Reads structured data from an XML string/bytes.
-    ///
-    /// This function is deprecated. The [`xml`] function now accepts bytes
-    /// directly.
     #[func(title = "Decode XML")]
     #[deprecated = "`xml.decode` is deprecated, directly pass bytes to `xml` instead"]
     pub fn decode(
diff --git a/crates/typst-library/src/loading/yaml.rs b/crates/typst-library/src/loading/yaml.rs
index 511c676c..4eeec28f 100644
--- a/crates/typst-library/src/loading/yaml.rs
+++ b/crates/typst-library/src/loading/yaml.rs
@@ -55,9 +55,6 @@ pub fn yaml(
 #[scope]
 impl yaml {
     /// Reads structured data from a YAML string/bytes.
-    ///
-    /// This function is deprecated. The [`yaml`] function now accepts bytes
-    /// directly.
     #[func(title = "Decode YAML")]
     #[deprecated = "`yaml.decode` is deprecated, directly pass bytes to `yaml` instead"]
     pub fn decode(
diff --git a/crates/typst-library/src/math/mod.rs b/crates/typst-library/src/math/mod.rs
index a97a19b0..2e6d42b1 100644
--- a/crates/typst-library/src/math/mod.rs
+++ b/crates/typst-library/src/math/mod.rs
@@ -27,119 +27,10 @@ pub use self::underover::*;
 use typst_utils::singleton;
 use unicode_math_class::MathClass;
 
-use crate::foundations::{
-    category, elem, Category, Content, Module, NativeElement, Scope,
-};
+use crate::foundations::{elem, Content, Module, NativeElement, Scope};
 use crate::layout::{Em, HElem};
 use crate::text::TextElem;
 
-/// Typst has special [syntax]($syntax/#math) and library functions to typeset
-/// mathematical formulas. Math formulas can be displayed inline with text or as
-/// separate blocks. They will be typeset into their own block if they start and
-/// end with at least one space (e.g. `[$ x^2 $]`).
-///
-/// # Variables
-/// In math, single letters are always displayed as is. Multiple letters,
-/// however, are interpreted as variables and functions. To display multiple
-/// letters verbatim, you can place them into quotes and to access single letter
-/// variables, you can use the [hash syntax]($scripting/#expressions).
-///
-/// ```example
-/// $ A = pi r^2 $
-/// $ "area" = pi dot "radius"^2 $
-/// $ cal(A) :=
-///     { x in RR | x "is natural" } $
-/// #let x = 5
-/// $ #x < 17 $
-/// ```
-///
-/// # Symbols
-/// Math mode makes a wide selection of [symbols]($category/symbols/sym) like
-/// `pi`, `dot`, or `RR` available. Many mathematical symbols are available in
-/// different variants. You can select between different variants by applying
-/// [modifiers]($symbol) to the symbol. Typst further recognizes a number of
-/// shorthand sequences like `=>` that approximate a symbol. When such a
-/// shorthand exists, the symbol's documentation lists it.
-///
-/// ```example
-/// $ x < y => x gt.eq.not y $
-/// ```
-///
-/// # Line Breaks
-/// Formulas can also contain line breaks. Each line can contain one or multiple
-/// _alignment points_ (`&`) which are then aligned.
-///
-/// ```example
-/// $ sum_(k=0)^n k
-///     &= 1 + ... + n \
-///     &= (n(n+1)) / 2 $
-/// ```
-///
-/// # Function calls
-/// Math mode supports special function calls without the hash prefix. In these
-/// "math calls", the argument list works a little differently than in code:
-///
-/// - Within them, Typst is still in "math mode". Thus, you can write math
-///   directly into them, but need to use hash syntax to pass code expressions
-///   (except for strings, which are available in the math syntax).
-/// - They support positional and named arguments, as well as argument
-///   spreading.
-/// - They don't support trailing content blocks.
-/// - They provide additional syntax for 2-dimensional argument lists. The
-///   semicolon (`;`) merges preceding arguments separated by commas into an
-///   array argument.
-///
-/// ```example
-/// $ frac(a^2, 2) $
-/// $ vec(1, 2, delim: "[") $
-/// $ mat(1, 2; 3, 4) $
-/// $ mat(..#range(1, 5).chunks(2)) $
-/// $ lim_x =
-///     op("lim", limits: #true)_x $
-/// ```
-///
-/// To write a verbatim comma or semicolon in a math call, escape it with a
-/// backslash. The colon on the other hand is only recognized in a special way
-/// if directly preceded by an identifier, so to display it verbatim in those
-/// cases, you can just insert a space before it.
-///
-/// Functions calls preceded by a hash are normal code function calls and not
-/// affected by these rules.
-///
-/// # Alignment
-/// When equations include multiple _alignment points_ (`&`), this creates
-/// blocks of alternatingly right- and left-aligned columns. In the example
-/// below, the expression `(3x + y) / 7` is right-aligned and `= 9` is
-/// left-aligned. The word "given" is also left-aligned because `&&` creates two
-/// alignment points in a row, alternating the alignment twice. `& &` and `&&`
-/// behave exactly the same way. Meanwhile, "multiply by 7" is right-aligned
-/// because just one `&` precedes it. Each alignment point simply alternates
-/// between right-aligned/left-aligned.
-///
-/// ```example
-/// $ (3x + y) / 7 &= 9 && "given" \
-///   3x + y &= 63 & "multiply by 7" \
-///   3x &= 63 - y && "subtract y" \
-///   x &= 21 - y/3 & "divide by 3" $
-/// ```
-///
-/// # Math fonts
-/// You can set the math font by with a [show-set rule]($styling/#show-rules) as
-/// demonstrated below. Note that only special OpenType math fonts are suitable
-/// for typesetting maths.
-///
-/// ```example
-/// #show math.equation: set text(font: "Fira Math")
-/// $ sum_(i in NN) 1 + i $
-/// ```
-///
-/// # Math module
-/// All math functions are part of the `math` [module]($scripting/#modules),
-/// which is available by default in equations. Outside of equations, they can
-/// be accessed with the `math.` prefix.
-#[category]
-pub static MATH: Category;
-
 // Spacings.
 pub const THIN: Em = Em::new(1.0 / 6.0);
 pub const MEDIUM: Em = Em::new(2.0 / 9.0);
@@ -150,7 +41,7 @@ pub const WIDE: Em = Em::new(2.0);
 /// Create a module with all math definitions.
 pub fn module() -> Module {
     let mut math = Scope::deduplicating();
-    math.start_category(MATH);
+    math.start_category(crate::Category::Math);
     math.define_elem::<EquationElem>();
     math.define_elem::<TextElem>();
     math.define_elem::<LrElem>();
diff --git a/crates/typst-library/src/model/mod.rs b/crates/typst-library/src/model/mod.rs
index 586e10ec..9bdbf001 100644
--- a/crates/typst-library/src/model/mod.rs
+++ b/crates/typst-library/src/model/mod.rs
@@ -40,19 +40,11 @@ pub use self::strong::*;
 pub use self::table::*;
 pub use self::terms::*;
 
-use crate::foundations::{category, Category, Scope};
-
-/// Document structuring.
-///
-/// Here, you can find functions to structure your document and interact with
-/// that structure. This includes section headings, figures, bibliography
-/// management, cross-referencing and more.
-#[category]
-pub static MODEL: Category;
+use crate::foundations::Scope;
 
 /// Hook up all `model` definitions.
 pub fn define(global: &mut Scope) {
-    global.start_category(MODEL);
+    global.start_category(crate::Category::Model);
     global.define_elem::<DocumentElem>();
     global.define_elem::<RefElem>();
     global.define_elem::<LinkElem>();
@@ -72,4 +64,5 @@ pub fn define(global: &mut Scope) {
     global.define_elem::<EmphElem>();
     global.define_elem::<StrongElem>();
     global.define_func::<numbering>();
+    global.reset_category();
 }
diff --git a/crates/typst-library/src/pdf/mod.rs b/crates/typst-library/src/pdf/mod.rs
index 3bd3b0c5..786a3637 100644
--- a/crates/typst-library/src/pdf/mod.rs
+++ b/crates/typst-library/src/pdf/mod.rs
@@ -4,21 +4,12 @@ mod embed;
 
 pub use self::embed::*;
 
-use crate::foundations::{category, Category, Module, Scope};
-
-/// PDF-specific functionality.
-#[category]
-pub static PDF: Category;
-
-/// Hook up the `pdf` module.
-pub(super) fn define(global: &mut Scope) {
-    global.start_category(PDF);
-    global.define("pdf", module());
-}
+use crate::foundations::{Module, Scope};
 
 /// Hook up all `pdf` definitions.
 pub fn module() -> Module {
-    let mut scope = Scope::deduplicating();
-    scope.define_elem::<EmbedElem>();
-    Module::new("pdf", scope)
+    let mut pdf = Scope::deduplicating();
+    pdf.start_category(crate::Category::Pdf);
+    pdf.define_elem::<EmbedElem>();
+    Module::new("pdf", pdf)
 }
diff --git a/crates/typst-library/src/symbols.rs b/crates/typst-library/src/symbols.rs
index 777f8172..0588ace9 100644
--- a/crates/typst-library/src/symbols.rs
+++ b/crates/typst-library/src/symbols.rs
@@ -1,19 +1,12 @@
 //! Modifiable symbols.
 
-use crate::foundations::{category, Category, Module, Scope, Symbol, Value};
-
-/// These two modules give names to symbols and emoji to make them easy to
-/// insert with a normal keyboard. Alternatively, you can also always directly
-/// enter Unicode symbols into your text and formulas. In addition to the
-/// symbols listed below, math mode defines `dif` and `Dif`. These are not
-/// normal symbol values because they also affect spacing and font style.
-#[category]
-pub static SYMBOLS: Category;
+use crate::foundations::{Module, Scope, Symbol, Value};
 
 /// Hook up all `symbol` definitions.
 pub(super) fn define(global: &mut Scope) {
-    global.start_category(SYMBOLS);
+    global.start_category(crate::Category::Symbols);
     extend_scope_from_codex_module(global, codex::ROOT);
+    global.reset_category();
 }
 
 /// Hook up all math `symbol` definitions, i.e., elements of the `sym` module.
diff --git a/crates/typst-library/src/text/mod.rs b/crates/typst-library/src/text/mod.rs
index f506397e..12f4e4c5 100644
--- a/crates/typst-library/src/text/mod.rs
+++ b/crates/typst-library/src/text/mod.rs
@@ -45,9 +45,9 @@ use typst_utils::singleton;
 use crate::diag::{bail, warning, HintedStrResult, SourceResult};
 use crate::engine::Engine;
 use crate::foundations::{
-    cast, category, dict, elem, Args, Array, Cast, Category, Construct, Content, Dict,
-    Fold, IntoValue, NativeElement, Never, NoneValue, Packed, PlainText, Regex, Repr,
-    Resolve, Scope, Set, Smart, StyleChain,
+    cast, dict, elem, Args, Array, Cast, Construct, Content, Dict, Fold, IntoValue,
+    NativeElement, Never, NoneValue, Packed, PlainText, Regex, Repr, Resolve, Scope, Set,
+    Smart, StyleChain,
 };
 use crate::layout::{Abs, Axis, Dir, Em, Length, Ratio, Rel};
 use crate::math::{EquationElem, MathSize};
@@ -55,15 +55,9 @@ use crate::model::ParElem;
 use crate::visualize::{Color, Paint, RelativeTo, Stroke};
 use crate::World;
 
-/// Text styling.
-///
-/// The [text function]($text) is of particular interest.
-#[category]
-pub static TEXT: Category;
-
 /// Hook up all `text` definitions.
 pub(super) fn define(global: &mut Scope) {
-    global.start_category(TEXT);
+    global.start_category(crate::Category::Text);
     global.define_elem::<TextElem>();
     global.define_elem::<LinebreakElem>();
     global.define_elem::<SmartQuoteElem>();
@@ -78,6 +72,7 @@ pub(super) fn define(global: &mut Scope) {
     global.define_func::<lower>();
     global.define_func::<upper>();
     global.define_func::<lorem>();
+    global.reset_category();
 }
 
 /// Customizes the look and layout of text in a variety of ways.
diff --git a/crates/typst-library/src/visualize/image/mod.rs b/crates/typst-library/src/visualize/image/mod.rs
index 9306eb6f..18d40caa 100644
--- a/crates/typst-library/src/visualize/image/mod.rs
+++ b/crates/typst-library/src/visualize/image/mod.rs
@@ -50,6 +50,17 @@ pub struct ImageElem {
     /// supported [formats]($image.format).
     ///
     /// For more details about paths, see the [Paths section]($syntax/#paths).
+    ///
+    /// ```example
+    /// #let original = read("diagram.svg")
+    /// #let changed = original.replace(
+    ///   "#2B80FF", // blue
+    ///   green.to-hex(),
+    /// )
+    ///
+    /// #image(bytes(original))
+    /// #image(bytes(changed))
+    /// ```
     #[required]
     #[parse(
         let source = args.expect::<Spanned<DataSource>>("source")?;
@@ -156,20 +167,6 @@ pub struct ImageElem {
 #[allow(clippy::too_many_arguments)]
 impl ImageElem {
     /// Decode a raster or vector graphic from bytes or a string.
-    ///
-    /// This function is deprecated. The [`image`] function now accepts bytes
-    /// directly.
-    ///
-    /// ```example
-    /// #let original = read("diagram.svg")
-    /// #let changed = original.replace(
-    ///   "#2B80FF", // blue
-    ///   green.to-hex(),
-    /// )
-    ///
-    /// #image.decode(original)
-    /// #image.decode(changed)
-    /// ```
     #[func(title = "Decode Image")]
     #[deprecated = "`image.decode` is deprecated, directly pass bytes to `image` instead"]
     pub fn decode(
diff --git a/crates/typst-library/src/visualize/mod.rs b/crates/typst-library/src/visualize/mod.rs
index 76849ac8..72a42065 100644
--- a/crates/typst-library/src/visualize/mod.rs
+++ b/crates/typst-library/src/visualize/mod.rs
@@ -24,19 +24,11 @@ pub use self::shape::*;
 pub use self::stroke::*;
 pub use self::tiling::*;
 
-use crate::foundations::{category, Category, Element, Scope, Type};
-
-/// Drawing and data visualization.
-///
-/// If you want to create more advanced drawings or plots, also have a look at
-/// the [CetZ](https://github.com/johannes-wolf/cetz) package as well as more
-/// specialized [packages]($universe) for your use case.
-#[category]
-pub static VISUALIZE: Category;
+use crate::foundations::{Element, Scope, Type};
 
 /// Hook up all visualize definitions.
 pub(super) fn define(global: &mut Scope) {
-    global.start_category(VISUALIZE);
+    global.start_category(crate::Category::Visualize);
     global.define_type::<Color>();
     global.define_type::<Gradient>();
     global.define_type::<Tiling>();
@@ -55,4 +47,5 @@ pub(super) fn define(global: &mut Scope) {
     global
         .define("pattern", Type::of::<Tiling>())
         .deprecated("the name `pattern` is deprecated, use `tiling` instead");
+    global.reset_category();
 }
diff --git a/crates/typst-library/src/visualize/path.rs b/crates/typst-library/src/visualize/path.rs
index 5d3439c0..c1cfde94 100644
--- a/crates/typst-library/src/visualize/path.rs
+++ b/crates/typst-library/src/visualize/path.rs
@@ -21,9 +21,6 @@ use crate::visualize::{FillRule, Paint, Stroke};
 ///   ((50%, 0pt), (40pt, 0pt)),
 /// )
 /// ```
-///
-/// # Deprecation
-/// This function is deprecated. The [`curve`] function should be used instead.
 #[elem(Show)]
 pub struct PathElem {
     /// How to fill the path.
diff --git a/crates/typst-macros/src/category.rs b/crates/typst-macros/src/category.rs
deleted file mode 100644
index 26ec879c..00000000
--- a/crates/typst-macros/src/category.rs
+++ /dev/null
@@ -1,59 +0,0 @@
-use heck::{ToKebabCase, ToTitleCase};
-use proc_macro2::TokenStream;
-use quote::quote;
-use syn::parse::{Parse, ParseStream};
-use syn::{Attribute, Ident, Result, Token, Type, Visibility};
-
-use crate::util::{documentation, foundations};
-
-/// Expand the `#[category]` macro.
-pub fn category(_: TokenStream, item: syn::Item) -> Result<TokenStream> {
-    let syn::Item::Verbatim(stream) = item else {
-        bail!(item, "expected bare static");
-    };
-
-    let BareStatic { attrs, vis, ident, ty, .. } = syn::parse2(stream)?;
-
-    let name = ident.to_string().to_kebab_case();
-    let title = name.to_title_case();
-    let docs = documentation(&attrs);
-
-    Ok(quote! {
-        #(#attrs)*
-        #[allow(rustdoc::broken_intra_doc_links)]
-        #vis static #ident: #ty = {
-            static DATA: #foundations::CategoryData = #foundations::CategoryData {
-                name: #name,
-                title: #title,
-                docs: #docs,
-            };
-            #foundations::Category::from_data(&DATA)
-        };
-    })
-}
-
-/// Parse a bare `pub static CATEGORY: Category;` item.
-#[allow(dead_code)]
-pub struct BareStatic {
-    pub attrs: Vec<Attribute>,
-    pub vis: Visibility,
-    pub static_token: Token![static],
-    pub ident: Ident,
-    pub colon_token: Token![:],
-    pub ty: Type,
-    pub semi_token: Token![;],
-}
-
-impl Parse for BareStatic {
-    fn parse(input: ParseStream) -> Result<Self> {
-        Ok(Self {
-            attrs: input.call(Attribute::parse_outer)?,
-            vis: input.parse()?,
-            static_token: input.parse()?,
-            ident: input.parse()?,
-            colon_token: input.parse()?,
-            ty: input.parse()?,
-            semi_token: input.parse()?,
-        })
-    }
-}
diff --git a/crates/typst-macros/src/lib.rs b/crates/typst-macros/src/lib.rs
index 578389c7..82e63ddc 100644
--- a/crates/typst-macros/src/lib.rs
+++ b/crates/typst-macros/src/lib.rs
@@ -5,7 +5,6 @@ extern crate proc_macro;
 #[macro_use]
 mod util;
 mod cast;
-mod category;
 mod elem;
 mod func;
 mod scope;
@@ -266,15 +265,6 @@ pub fn scope(stream: BoundaryStream, item: BoundaryStream) -> BoundaryStream {
         .into()
 }
 
-/// Defines a category of definitions.
-#[proc_macro_attribute]
-pub fn category(stream: BoundaryStream, item: BoundaryStream) -> BoundaryStream {
-    let item = syn::parse_macro_input!(item as syn::Item);
-    category::category(stream.into(), item)
-        .unwrap_or_else(|err| err.to_compile_error())
-        .into()
-}
-
 /// Implements `Reflect`, `FromValue`, and `IntoValue` for a type.
 ///
 /// - `Reflect` makes Typst's runtime aware of the type's characteristics.