Documentation provider

Cargo.lock

@@ -366,6 +366,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "getopts"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "14dbbfd5c71d70241ecf9e6f13737f7b5ce823821063188d7e46c41d371eebd5"
+dependencies = [
+ "unicode-width",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.2.8"
@@ -387,6 +396,18 @@ dependencies = [
  "weezl",
 ]
 
+[[package]]
+name = "hashbrown"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
+
+[[package]]
+name = "heck"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8"
+
 [[package]]
 name = "hypher"
 version = "0.1.1"
@@ -447,6 +468,35 @@ dependencies = [
  "png",
 ]
 
+[[package]]
+name = "include_dir"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "18762faeff7122e89e0857b02f7ce6fcc0d101d5e9ad2ad7846cc01d61b7f19e"
+dependencies = [
+ "include_dir_macros",
+]
+
+[[package]]
+name = "include_dir_macros"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b139284b5cf57ecfa712bcc66950bb635b31aff41c188e8a4cfc758eca374a3f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+]
+
+[[package]]
+name = "indexmap"
+version = "1.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1885e79c1fc4b10f0e172c475f458b7f7b93061064d98c3293e98c5ba0c8b399"
+dependencies = [
+ "autocfg",
+ "hashbrown",
+]
+
 [[package]]
 name = "inotify"
 version = "0.9.6"
@@ -550,6 +600,12 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "linked-hash-map"
+version = "0.5.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0717cef1bc8b636c6e1c1bbdefc09e6322da8a9321966e8928ef80d20f7f770f"
+
 [[package]]
 name = "lipsum"
 version = "0.8.2"
@@ -725,6 +781,18 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "pulldown-cmark"
+version = "0.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d9cc634bc78768157b5cbfe988ffcd1dcba95cd2b2f03a88316c08c6d00ed63"
+dependencies = [
+ "bitflags",
+ "getopts",
+ "memchr",
+ "unicase",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.23"
@@ -920,6 +988,18 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "serde_yaml"
+version = "0.8.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "578a7433b776b56a35785ed5ce9a7e777ac0598aac5a6dd1b4b18a307c7fc71b"
+dependencies = [
+ "indexmap",
+ "ryu",
+ "serde",
+ "yaml-rust",
+]
+
 [[package]]
 name = "simplecss"
 version = "0.2.1"
@@ -1133,6 +1213,24 @@ dependencies = [
  "walkdir",
 ]
 
+[[package]]
+name = "typst-docs"
+version = "0.1.0"
+dependencies = [
+ "comemo",
+ "heck",
+ "include_dir",
+ "once_cell",
+ "pulldown-cmark",
+ "serde",
+ "serde_yaml",
+ "typst",
+ "typst-library",
+ "unicode_names2",
+ "unscanny",
+ "yaml-front-matter",
+]
+
 [[package]]
 name = "typst-library"
 version = "0.1.0"
@@ -1184,6 +1282,15 @@ dependencies = [
  "walkdir",
 ]
 
+[[package]]
+name = "unicase"
+version = "2.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "50f37be617794602aabbeee0be4f259dc1778fabe05e2d67ee8f79326d5cb4f6"
+dependencies = [
+ "version_check",
+]
+
 [[package]]
 name = "unicode-bidi"
 version = "0.3.8"
@@ -1243,6 +1350,12 @@ version = "0.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f962df74c8c05a667b5ee8bcf162993134c104e96440b663c8daa176dc772d8c"
 
+[[package]]
+name = "unicode_names2"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "446c96c6dd42604779487f0a981060717156648c1706aa1f464677f03c6cc059"
+
 [[package]]
 name = "unscanny"
 version = "0.1.0"
@@ -1269,6 +1382,12 @@ dependencies = [
  "svgtypes",
 ]
 
+[[package]]
+name = "version_check"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "49874b5167b65d7193b8aba1567f5c7d93d001cafc34600cee003eda787e483f"
+
 [[package]]
 name = "walkdir"
 version = "2.3.2"
@@ -1445,3 +1564,22 @@ name = "xmlparser"
 version = "0.13.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4d25c75bf9ea12c4040a97f829154768bbbce366287e2dc044af160cd79a13fd"
+
+[[package]]
+name = "yaml-front-matter"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a94fb32d2b438e3fddf901fbfe9eb87b34d63853ca6c6da5d2ab7e27031e0bae"
+dependencies = [
+ "serde",
+ "serde_yaml",
+]
+
+[[package]]
+name = "yaml-rust"
+version = "0.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56c1936c4cc7a1c9ab21a1ebb602eb942ba868cbd44a99cb7cdc5892335e1c85"
+dependencies = [
+ "linked-hash-map",
+]

Cargo.toml

@@ -5,7 +5,7 @@ authors = ["The Typst Project Developers"]
 edition = "2021"
 
 [workspace]
-members = ["cli", "library", "macros", "tests"]
+members = ["cli", "docs", "library", "macros", "tests"]
 
 [lib]
 doctest = false

docs/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "typst-docs"
+version = "0.1.0"
+authors = ["The Typst Project Developers"]
+edition = "2021"
+
+[lib]
+test = false
+doctest = false
+bench = false
+
+[dependencies]
+typst = { path = ".." }
+typst-library = { path = "../library" }
+unscanny = "0.1"
+include_dir = "0.7"
+pulldown-cmark = "0.9"
+comemo = { git = "https://github.com/typst/comemo" }
+serde = "1"
+serde_yaml = "0.8"
+heck = "0.4"
+yaml-front-matter = "0.1"
+unicode_names2 = "0.6.0"
+once_cell = "1"

docs/src/html.rs

@@ -0,0 +1,328 @@
+use comemo::Prehashed;
+use md::escape::escape_html;
+use pulldown_cmark as md;
+use typst::diag::FileResult;
+use typst::font::{Font, FontBook};
+use typst::geom::{Point, Size};
+use typst::syntax::{Source, SourceId};
+use typst::util::Buffer;
+use typst::World;
+use yaml_front_matter::YamlFrontMatter;
+
+use super::*;
+
+/// HTML documentation.
+#[derive(Serialize)]
+#[serde(transparent)]
+pub struct Html {
+    raw: String,
+    #[serde(skip)]
+    md: String,
+    #[serde(skip)]
+    description: Option<String>,
+}
+
+impl Html {
+    /// Create HTML from a raw string.
+    pub fn new(raw: String) -> Self {
+        Self { md: String::new(), raw, description: None }
+    }
+
+    /// Convert markdown to HTML.
+    #[track_caller]
+    pub fn markdown(resolver: &dyn Resolver, md: &str) -> Self {
+        let mut text = md;
+        let mut description = None;
+        let document = YamlFrontMatter::parse::<Metadata>(&md);
+        if let Ok(document) = &document {
+            text = &document.content;
+            description = Some(document.metadata.description.clone())
+        }
+
+        let options = md::Options::ENABLE_TABLES | md::Options::ENABLE_HEADING_ATTRIBUTES;
+
+        let mut handler = Handler::new(resolver);
+        let iter = md::Parser::new_ext(text, options)
+            .filter_map(|mut event| handler.handle(&mut event).then(|| event));
+
+        let mut raw = String::new();
+        md::html::push_html(&mut raw, iter);
+        raw.truncate(raw.trim_end().len());
+        Html { md: text.into(), raw, description }
+    }
+
+    /// The raw HTML.
+    pub fn as_str(&self) -> &str {
+        &self.raw
+    }
+
+    /// The original Markdown, if any.
+    pub fn md(&self) -> &str {
+        &self.md
+    }
+
+    /// The title of the HTML.
+    ///
+    /// Returns `None` if the HTML doesn't start with an `h1` tag.
+    pub fn title(&self) -> Option<&str> {
+        let mut s = Scanner::new(&self.raw);
+        s.eat_if("<h1>").then(|| s.eat_until("</h1>"))
+    }
+
+    /// The description from the front matter.
+    pub fn description(&self) -> Option<String> {
+        self.description.clone()
+    }
+}
+
+impl Debug for Html {
+    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
+        write!(f, "Html({:?})", self.title().unwrap_or(".."))
+    }
+}
+
+/// Front matter metadata.
+#[derive(Deserialize)]
+struct Metadata {
+    description: String,
+}
+
+struct Handler<'a> {
+    resolver: &'a dyn Resolver,
+    lang: Option<String>,
+}
+
+impl<'a> Handler<'a> {
+    fn new(resolver: &'a dyn Resolver) -> Self {
+        Self { resolver, lang: None }
+    }
+
+    fn handle(&mut self, event: &mut md::Event) -> bool {
+        let lang = self.lang.take();
+        match event {
+            // Rewrite Markdown images.
+            md::Event::Start(md::Tag::Image(_, path, _)) => {
+                *path = self.handle_image(path).into();
+            }
+
+            // Rewrite HTML images.
+            md::Event::Html(html) if html.starts_with("<img") => {
+                let needle = "src=\"";
+                let offset = html.find(needle).unwrap() + needle.len();
+                let len = html[offset..].find('"').unwrap();
+                let range = offset..offset + len;
+                let path = &html[range.clone()];
+                let mut buf = html.to_string();
+                buf.replace_range(range, &self.handle_image(path));
+                *html = buf.into();
+            }
+
+            // Rewrite links.
+            md::Event::Start(md::Tag::Link(ty, dest, _)) => {
+                assert!(
+                    matches!(ty, md::LinkType::Inline | md::LinkType::Reference),
+                    "unsupported link type: {ty:?}",
+                );
+
+                let mut link = self
+                    .handle_link(dest)
+                    .unwrap_or_else(|| panic!("invalid link: {dest}"));
+
+                if !link.contains('#') && !link.ends_with('/') {
+                    link.push('/');
+                }
+
+                *dest = link.into();
+            }
+
+            // Inline raw.
+            md::Event::Code(code) => {
+                let mut chars = code.chars();
+                let parser = match (chars.next(), chars.next_back()) {
+                    (Some('['), Some(']')) => typst::syntax::parse,
+                    (Some('{'), Some('}')) => typst::syntax::parse_code,
+                    _ => return true,
+                };
+
+                let root = parser(&code[1..code.len() - 1]);
+                let html = typst::ide::highlight_html(&root);
+                *event = md::Event::Html(html.into());
+            }
+
+            // Code blocks.
+            md::Event::Start(md::Tag::CodeBlock(md::CodeBlockKind::Fenced(lang))) => {
+                self.lang = Some(lang.as_ref().into());
+                return false;
+            }
+            md::Event::End(md::Tag::CodeBlock(md::CodeBlockKind::Fenced(_))) => {
+                return false;
+            }
+
+            // Example with preview.
+            md::Event::Text(text) => {
+                let Some(lang) = lang.as_deref() else { return true };
+                let html = code_block(self.resolver, lang, text);
+                *event = md::Event::Html(html.raw.into());
+            }
+
+            _ => {}
+        }
+
+        true
+    }
+
+    fn handle_image(&self, path: &str) -> String {
+        let data = IMAGES
+            .get_file(path)
+            .unwrap_or_else(|| panic!("missing image: {path}"))
+            .contents();
+        self.resolver.image(&path, data).into()
+    }
+
+    fn handle_link(&self, link: &str) -> Option<String> {
+        if link.starts_with(['#', 'h']) {
+            return Some(link.into());
+        } else if !link.starts_with('$') {
+            return None;
+        }
+
+        let root = link.split('/').next()?;
+        let rest = &link[root.len()..].trim_matches('/');
+        let base = match root {
+            "$tutorial" => "/docs/tutorial/",
+            "$reference" => "/docs/reference/",
+            "$category" => "/docs/reference/",
+            "$syntax" => "/docs/reference/syntax/",
+            "$styling" => "/docs/reference/styling/",
+            "$scripting" => "/docs/reference/scripting/",
+            "$types" => "/docs/reference/types/",
+            "$community" => "/docs/community/",
+            "$type" => "/docs/reference/types/",
+            "$func" => "/docs/reference/",
+            _ => panic!("unknown link root: {root}"),
+        };
+
+        let mut route = base.to_string();
+        if root == "$type" && rest.contains('.') {
+            let mut parts = rest.split('.');
+            let ty = parts.next()?;
+            let method = parts.next()?;
+            route.push_str(ty);
+            route.push_str("/#methods--");
+            route.push_str(method);
+        } else if root == "$func" {
+            let mut parts = rest.split('.');
+            let name = parts.next()?;
+            let param = parts.next();
+            let value =
+                LIBRARY.global.get(name).or_else(|_| LIBRARY.math.get(name)).ok()?;
+            let Value::Func(func) = value else { return None };
+            let info = func.info()?;
+            route.push_str(info.category);
+            route.push('/');
+            route.push_str(name);
+            if let Some(param) = param {
+                route.push_str("#parameters--");
+                route.push_str(param);
+            }
+        } else {
+            route.push_str(rest);
+        }
+
+        Some(route)
+    }
+}
+
+/// Render a code block to HTML.
+fn code_block(resolver: &dyn Resolver, lang: &str, text: &str) -> Html {
+    let mut display = String::new();
+    let mut compile = String::new();
+    for line in text.lines() {
+        if let Some(suffix) = line.strip_prefix(">>>") {
+            compile.push_str(suffix);
+            compile.push('\n');
+        } else if let Some(suffix) = line.strip_prefix("<<< ") {
+            display.push_str(suffix);
+            display.push('\n');
+        } else {
+            display.push_str(line);
+            display.push('\n');
+            compile.push_str(line);
+            compile.push('\n');
+        }
+    }
+
+    let mut parts = lang.split(':');
+    let lang = parts.next().unwrap_or(lang);
+    let mut zoom: Option<[Abs; 4]> = None;
+    if let Some(args) = parts.next() {
+        zoom = args
+            .split(',')
+            .take(4)
+            .map(|s| Abs::pt(s.parse().unwrap()))
+            .collect::<Vec<_>>()
+            .try_into()
+            .ok();
+    }
+
+    if !matches!(lang, "example" | "typ") {
+        let mut buf = String::from("<pre>");
+        escape_html(&mut buf, &display).unwrap();
+        buf.push_str("</pre>");
+        return Html::new(buf);
+    }
+
+    let root = typst::syntax::parse(&display);
+    let highlighted = Html::new(typst::ide::highlight_html(&root));
+    if lang == "typ" {
+        return Html::new(format!("<pre>{}</pre>", highlighted.as_str()));
+    }
+
+    let source = Source::new(SourceId::from_u16(0), Path::new("main.typ"), compile);
+    let world = DocWorld(source);
+    let mut frame = match typst::compile(&world, &world.0) {
+        Ok(doc) => doc.pages.into_iter().next().unwrap(),
+        Err(err) => panic!("failed to compile {text}: {err:?}"),
+    };
+
+    if let Some([x, y, w, h]) = zoom {
+        frame.translate(Point::new(-x, -y));
+        *frame.size_mut() = Size::new(w, h);
+    }
+
+    resolver.example(highlighted, frame)
+}
+
+/// World for example compilations.
+struct DocWorld(Source);
+
+impl World for DocWorld {
+    fn library(&self) -> &Prehashed<Library> {
+        &LIBRARY
+    }
+
+    fn book(&self) -> &Prehashed<FontBook> {
+        &FONTS.0
+    }
+
+    fn font(&self, id: usize) -> Option<Font> {
+        Some(FONTS.1[id].clone())
+    }
+
+    fn file(&self, path: &Path) -> FileResult<Buffer> {
+        Ok(FILES
+            .get_file(path)
+            .unwrap_or_else(|| panic!("failed to load {path:?}"))
+            .contents()
+            .into())
+    }
+
+    fn resolve(&self, _: &Path) -> FileResult<SourceId> {
+        unimplemented!()
+    }
+
+    fn source(&self, id: SourceId) -> &Source {
+        assert_eq!(id.into_u16(), 0, "invalid source id");
+        &self.0
+    }
+}

docs/src/lib.rs

@@ -0,0 +1,744 @@
+//! Documentation provider for Typst.
+
+mod html;
+
+pub use html::Html;
+
+use std::fmt::{self, Debug, Formatter};
+use std::path::Path;
+
+use comemo::Prehashed;
+use heck::ToTitleCase;
+use include_dir::{include_dir, Dir};
+use once_cell::sync::Lazy;
+use serde::de::DeserializeOwned;
+use serde::{Deserialize, Serialize};
+use serde_yaml as yaml;
+use typst::doc::Frame;
+use typst::font::{Font, FontBook};
+use typst::geom::{Abs, Sides, Smart};
+use typst::model::{CastInfo, Func, FuncInfo, Library, Module, ParamInfo, Value};
+use typst_library::layout::PageNode;
+use unscanny::Scanner;
+
+static SRC: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/src");
+static FILES: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/../assets/files");
+static IMAGES: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/../assets/images");
+static DETAILS: Lazy<yaml::Mapping> = Lazy::new(|| yaml("reference/details.yml"));
+static GROUPS: Lazy<Vec<GroupData>> = Lazy::new(|| yaml("reference/groups.yml"));
+
+static FONTS: Lazy<(Prehashed<FontBook>, Vec<Font>)> = Lazy::new(|| {
+    static DIR: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/../assets/fonts");
+    let fonts: Vec<_> = DIR
+        .files()
+        .flat_map(|file| Font::iter(file.contents().into()))
+        .collect();
+    let book = FontBook::from_fonts(&fonts);
+    (Prehashed::new(book), fonts)
+});
+
+static LIBRARY: Lazy<Prehashed<Library>> = Lazy::new(|| {
+    let mut lib = typst_library::build();
+    lib.styles.set(PageNode::WIDTH, Smart::Custom(Abs::pt(240.0).into()));
+    lib.styles.set(PageNode::HEIGHT, Smart::Auto);
+    lib.styles
+        .set(PageNode::MARGIN, Sides::splat(Some(Smart::Custom(Abs::pt(15.0).into()))));
+    typst::model::set_lang_items(lib.items.clone());
+    Prehashed::new(lib)
+});
+
+/// Build documentation pages.
+pub fn provide(resolver: &dyn Resolver) -> Vec<PageModel> {
+    vec![
+        markdown_page(resolver, "/docs/", "general/overview.md").with_route("/docs/"),
+        tutorial_page(resolver),
+        reference_page(resolver),
+        markdown_page(resolver, "/docs/", "general/changelog.md"),
+        markdown_page(resolver, "/docs/", "general/community.md"),
+    ]
+}
+
+/// Resolve consumer dependencies.
+pub trait Resolver {
+    /// Produce an URL for an image file.
+    fn image(&self, filename: &str, data: &[u8]) -> String;
+
+    /// Produce HTML for an example.
+    fn example(&self, source: Html, frame: Frame) -> Html;
+}
+
+/// Details about a documentation page and its children.
+#[derive(Debug, Serialize)]
+pub struct PageModel {
+    pub route: String,
+    pub title: String,
+    pub description: String,
+    pub part: Option<&'static str>,
+    pub body: BodyModel,
+    pub children: Vec<Self>,
+}
+
+impl PageModel {
+    fn with_route(self, route: &str) -> Self {
+        Self { route: route.into(), ..self }
+    }
+
+    fn with_part(self, part: &'static str) -> Self {
+        Self { part: Some(part), ..self }
+    }
+}
+
+/// Details about the body of a documentation page.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+#[serde(tag = "kind", content = "content")]
+pub enum BodyModel {
+    Html(Html),
+    Category(CategoryModel),
+    Func(FuncModel),
+    Funcs(FuncsModel),
+    Type(TypeModel),
+    Symbols(SymbolsModel),
+}
+
+/// Build the tutorial.
+fn tutorial_page(resolver: &dyn Resolver) -> PageModel {
+    let mut page = markdown_page(resolver, "/docs/", "tutorial/welcome.md");
+    page.children = SRC
+        .get_dir("tutorial")
+        .unwrap()
+        .files()
+        .filter(|file| file.path() != Path::new("tutorial/welcome.md"))
+        .map(|file| markdown_page(resolver, "/docs/tutorial/", file.path()))
+        .collect();
+    page
+}
+
+/// Build the reference.
+fn reference_page(resolver: &dyn Resolver) -> PageModel {
+    let mut page = markdown_page(resolver, "/docs/", "reference/welcome.md");
+    page.children = vec![
+        markdown_page(resolver, "/docs/reference/", "reference/syntax.md")
+            .with_part("Language"),
+        markdown_page(resolver, "/docs/reference/", "reference/styling.md"),
+        markdown_page(resolver, "/docs/reference/", "reference/scripting.md"),
+        types_page(resolver, "/docs/reference/"),
+        category_page(resolver, "basics").with_part("Content"),
+        category_page(resolver, "text"),
+        category_page(resolver, "math"),
+        category_page(resolver, "layout"),
+        category_page(resolver, "visualize"),
+        category_page(resolver, "meta"),
+        category_page(resolver, "symbols"),
+        category_page(resolver, "foundations").with_part("Compute"),
+        category_page(resolver, "calculate"),
+        category_page(resolver, "construct"),
+        category_page(resolver, "data-loading"),
+        category_page(resolver, "utility"),
+    ];
+    page
+}
+
+/// Create a page from a markdown file.
+#[track_caller]
+fn markdown_page(
+    resolver: &dyn Resolver,
+    parent: &str,
+    path: impl AsRef<Path>,
+) -> PageModel {
+    assert!(parent.starts_with('/') && parent.ends_with('/'));
+    let md = SRC.get_file(path).unwrap().contents_utf8().unwrap();
+    let html = Html::markdown(resolver, md);
+    let title = html.title().expect("chapter lacks a title").to_string();
+    PageModel {
+        route: format!("{parent}{}/", urlify(&title)),
+        title,
+        description: html.description().unwrap(),
+        part: None,
+        body: BodyModel::Html(html),
+        children: vec![],
+    }
+}
+
+/// Details about a category.
+#[derive(Debug, Serialize)]
+pub struct CategoryModel {
+    pub name: String,
+    pub details: Html,
+    pub kind: &'static str,
+    pub items: Vec<CategoryItem>,
+}
+
+/// Details about a category item.
+#[derive(Debug, Serialize)]
+pub struct CategoryItem {
+    pub name: String,
+    pub route: String,
+    pub oneliner: String,
+    pub code: bool,
+}
+
+/// Create a page for a category.
+#[track_caller]
+fn category_page(resolver: &dyn Resolver, category: &str) -> PageModel {
+    let route = format!("/docs/reference/{category}/");
+    let mut children = vec![];
+    let mut items = vec![];
+
+    let focus = match category {
+        "math" => &LIBRARY.math,
+        "calculate" => module(&LIBRARY.global, "calc"),
+        _ => &LIBRARY.global,
+    };
+
+    let grouped = match category {
+        "math" => GROUPS.as_slice(),
+        _ => &[],
+    };
+
+    // Add functions.
+    for (_, value) in focus.scope().iter() {
+        let Value::Func(func) = value else { continue };
+        let Some(info) = func.info() else { continue };
+        if info.category != category {
+            continue;
+        }
+
+        // Skip grouped functions.
+        if grouped
+            .iter()
+            .flat_map(|merge| &merge.functions)
+            .any(|f| f == info.name)
+        {
+            continue;
+        }
+
+        let subpage = function_page(resolver, &route, func, info);
+        items.push(CategoryItem {
+            name: info.name.into(),
+            route: subpage.route.clone(),
+            oneliner: oneliner(info.docs).into(),
+            code: true,
+        });
+        children.push(subpage);
+    }
+
+    // Add grouped functions.
+    for group in grouped {
+        let mut functions = vec![];
+        for name in &group.functions {
+            let value = focus.get(&name).unwrap();
+            let Value::Func(func) = value else { panic!("not a function") };
+            let info = func.info().unwrap();
+            functions.push(func_model(resolver, func, info));
+        }
+
+        let route = format!("{}{}/", route, group.name);
+        items.push(CategoryItem {
+            name: group.name.clone(),
+            route: route.clone(),
+            oneliner: oneliner(&group.description).into(),
+            code: false,
+        });
+        children.push(PageModel {
+            route,
+            title: group.title.clone(),
+            description: format!("Documentation for {} group of functions.", group.name),
+            part: None,
+            body: BodyModel::Funcs(FuncsModel {
+                name: group.name.clone(),
+                details: Html::markdown(resolver, &group.description),
+                functions,
+            }),
+            children: vec![],
+        });
+    }
+
+    children.sort_by_cached_key(|child| child.title.clone());
+    items.sort_by_cached_key(|item| item.name.clone());
+
+    // Add symbol pages. These are ordered manually.
+    if category == "symbols" {
+        for module in ["sym", "emoji"] {
+            let subpage = symbol_page(resolver, &route, module);
+            items.push(CategoryItem {
+                name: module.into(),
+                route: subpage.route.clone(),
+                oneliner: oneliner(details(module)).into(),
+                code: true,
+            });
+            children.push(subpage);
+        }
+    }
+
+    let name = category.to_title_case();
+    PageModel {
+        route,
+        title: name.clone(),
+        description: format!("Documentation for functions related to {name} in Typst."),
+        part: None,
+        body: BodyModel::Category(CategoryModel {
+            name,
+            details: Html::markdown(resolver, details(category)),
+            kind: match category {
+                "symbols" => "Modules",
+                _ => "Functions",
+            },
+            items,
+        }),
+        children,
+    }
+}
+
+/// Details about a function.
+#[derive(Debug, Serialize)]
+pub struct FuncModel {
+    pub name: &'static str,
+    pub oneliner: &'static str,
+    pub details: Html,
+    pub showable: bool,
+    pub params: Vec<ParamModel>,
+    pub returns: Vec<&'static str>,
+}
+
+/// Details about a group of functions.
+#[derive(Debug, Serialize)]
+pub struct FuncsModel {
+    pub name: String,
+    pub details: Html,
+    pub functions: Vec<FuncModel>,
+}
+
+/// Create a page for a function.
+fn function_page(
+    resolver: &dyn Resolver,
+    parent: &str,
+    func: &Func,
+    info: &FuncInfo,
+) -> PageModel {
+    PageModel {
+        route: format!("{parent}{}/", urlify(info.name)),
+        title: info.display.to_string(),
+        description: format!("Documentation for the `{}` function.", info.name),
+        part: None,
+        body: BodyModel::Func(func_model(resolver, func, info)),
+        children: vec![],
+    }
+}
+
+/// Produce a function's model.
+fn func_model(resolver: &dyn Resolver, func: &Func, info: &FuncInfo) -> FuncModel {
+    FuncModel {
+        name: info.name.into(),
+        oneliner: oneliner(info.docs),
+        details: Html::markdown(resolver, info.docs),
+        showable: func.select(None).is_ok() && info.category != "math",
+        params: info.params.iter().map(|param| param_model(resolver, param)).collect(),
+        returns: info.returns.clone(),
+    }
+}
+
+/// Details about a function parameter.
+#[derive(Debug, Serialize)]
+pub struct ParamModel {
+    pub name: &'static str,
+    pub details: Html,
+    pub example: Option<Html>,
+    pub types: Vec<&'static str>,
+    pub strings: Vec<StrParam>,
+    pub positional: bool,
+    pub named: bool,
+    pub required: bool,
+    pub variadic: bool,
+    pub settable: bool,
+}
+
+/// A specific string that can be passed as an argument.
+#[derive(Debug, Serialize)]
+pub struct StrParam {
+    pub string: String,
+    pub details: Html,
+}
+
+/// Produce a parameter's model.
+fn param_model(resolver: &dyn Resolver, info: &ParamInfo) -> ParamModel {
+    let mut types = vec![];
+    let mut strings = vec![];
+    casts(resolver, &mut types, &mut strings, &info.cast);
+    if !strings.is_empty() && !types.contains(&"string") {
+        types.push("string");
+    }
+    types.sort_by_key(|ty| type_index(ty));
+
+    let mut details = info.docs;
+    let mut example = None;
+    if let Some(mut i) = info.docs.find("```example") {
+        while info.docs[..i].ends_with('`') {
+            i -= 1;
+        }
+        details = &info.docs[..i];
+        example = Some(&info.docs[i..]);
+    }
+
+    ParamModel {
+        name: info.name,
+        details: Html::markdown(resolver, details),
+        example: example.map(|md| Html::markdown(resolver, md)),
+        types,
+        strings,
+        positional: info.positional,
+        named: info.named,
+        required: info.required,
+        variadic: info.variadic,
+        settable: info.settable,
+    }
+}
+
+/// Process cast information into types and strings.
+fn casts(
+    resolver: &dyn Resolver,
+    types: &mut Vec<&'static str>,
+    strings: &mut Vec<StrParam>,
+    info: &CastInfo,
+) {
+    match info {
+        CastInfo::Any => types.push("any"),
+        CastInfo::Value(Value::Str(string), docs) => strings.push(StrParam {
+            string: string.to_string(),
+            details: Html::markdown(resolver, docs),
+        }),
+        CastInfo::Value(..) => {}
+        CastInfo::Type(ty) => types.push(ty),
+        CastInfo::Union(options) => {
+            for option in options {
+                casts(resolver, types, strings, option);
+            }
+        }
+    }
+}
+
+/// A collection of symbols.
+#[derive(Debug, Serialize)]
+pub struct TypeModel {
+    pub name: String,
+    pub oneliner: &'static str,
+    pub details: Html,
+    pub methods: Vec<MethodModel>,
+}
+
+/// Details about a built-in method on a type.
+#[derive(Debug, Serialize)]
+pub struct MethodModel {
+    pub name: &'static str,
+    pub details: Html,
+    pub params: Vec<ParamModel>,
+    pub returns: Vec<&'static str>,
+}
+
+/// Create a page for the types.
+fn types_page(resolver: &dyn Resolver, parent: &str) -> PageModel {
+    let route = format!("{parent}types/");
+    let mut children = vec![];
+    let mut items = vec![];
+
+    for model in type_models(resolver) {
+        let route = format!("{route}{}/", model.name);
+        items.push(CategoryItem {
+            name: model.name.clone(),
+            route: route.clone(),
+            oneliner: model.oneliner.into(),
+            code: true,
+        });
+        children.push(PageModel {
+            route,
+            title: model.name.to_title_case(),
+            description: format!("Documentation for the `{}` type.", model.name),
+            part: None,
+            body: BodyModel::Type(model),
+            children: vec![],
+        });
+    }
+
+    PageModel {
+        route,
+        title: "Types".into(),
+        description: "Documentation for Typst's built-in types.".into(),
+        part: None,
+        body: BodyModel::Category(CategoryModel {
+            name: "Types".into(),
+            details: Html::markdown(resolver, details("types")),
+            kind: "Types",
+            items,
+        }),
+        children,
+    }
+}
+
+/// Produce the types' models.
+fn type_models(resolver: &dyn Resolver) -> Vec<TypeModel> {
+    let file = SRC.get_file("reference/types.md").unwrap();
+    let text = file.contents_utf8().unwrap();
+
+    let mut s = unscanny::Scanner::new(text);
+    let mut types = vec![];
+
+    while s.eat_if("# ") {
+        let part = s.eat_until("\n# ");
+        types.push(type_model(resolver, part));
+        s.eat_if('\n');
+    }
+
+    types
+}
+
+/// Produce a type's model.
+fn type_model(resolver: &dyn Resolver, part: &'static str) -> TypeModel {
+    let mut s = unscanny::Scanner::new(part);
+    let display = s.eat_until('\n').trim();
+    let docs = s.eat_until("\n## Methods").trim();
+
+    s.eat_whitespace();
+
+    let mut methods = vec![];
+    if s.eat_if("## Methods") {
+        s.eat_until("\n### ");
+        while s.eat_if("\n### ") {
+            methods.push(method_model(resolver, s.eat_until("\n### ")));
+        }
+    }
+
+    TypeModel {
+        name: display.to_lowercase(),
+        oneliner: oneliner(docs),
+        details: Html::markdown(resolver, docs),
+        methods,
+    }
+}
+
+/// Produce a method's model.
+fn method_model(resolver: &dyn Resolver, part: &'static str) -> MethodModel {
+    let mut s = unscanny::Scanner::new(part);
+    let mut params = vec![];
+    let mut returns = vec![];
+
+    let name = s.eat_until('(').trim();
+    s.expect("()");
+    let docs = s.eat_until("\n- ").trim();
+
+    while s.eat_if("\n- ") {
+        let name = s.eat_until(':');
+        s.expect(": ");
+        let types: Vec<_> =
+            s.eat_until(['(', '\n']).split(" or ").map(str::trim).collect();
+        if !types.iter().all(|ty| type_index(ty) != usize::MAX) {
+            panic!(
+                "unknown type in method {} parameter {}",
+                name,
+                types.iter().find(|ty| type_index(ty) == usize::MAX).unwrap()
+            )
+        }
+
+        if name == "returns" {
+            returns = types;
+            continue;
+        }
+
+        s.expect('(');
+
+        let mut named = false;
+        let mut positional = false;
+        let mut required = false;
+        let mut variadic = false;
+        for part in s.eat_until(')').split(',').map(str::trim) {
+            match part {
+                "named" => named = true,
+                "positional" => positional = true,
+                "required" => required = true,
+                "variadic" => variadic = true,
+                _ => panic!("unknown parameter flag {:?}", part),
+            }
+        }
+
+        s.expect(')');
+
+        params.push(ParamModel {
+            name,
+            details: Html::markdown(resolver, s.eat_until("\n- ").trim()),
+            example: None,
+            types,
+            strings: vec![],
+            positional,
+            named,
+            required,
+            variadic,
+            settable: false,
+        });
+    }
+
+    MethodModel {
+        name,
+        details: Html::markdown(resolver, docs),
+        params,
+        returns,
+    }
+}
+
+/// A collection of symbols.
+#[derive(Debug, Serialize)]
+pub struct SymbolsModel {
+    pub name: &'static str,
+    pub details: Html,
+    pub list: Vec<SymbolModel>,
+}
+
+/// Details about a symbol.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SymbolModel {
+    pub name: String,
+    pub shorthand: Option<&'static str>,
+    pub codepoint: u32,
+    pub accent: bool,
+    pub unicode_name: Option<String>,
+    pub alternates: Vec<String>,
+}
+
+/// Create a page for symbols.
+fn symbol_page(resolver: &dyn Resolver, parent: &str, name: &str) -> PageModel {
+    let module = &module(&LIBRARY.global, name);
+
+    let mut list = vec![];
+    for (name, value) in module.scope().iter() {
+        let Value::Symbol(symbol) = value else { continue };
+        let complete = |variant: &str| {
+            if variant.is_empty() {
+                name.into()
+            } else {
+                format!("{}.{}", name, variant)
+            }
+        };
+
+        for (variant, c) in symbol.variants() {
+            list.push(SymbolModel {
+                name: complete(variant),
+                shorthand: typst::syntax::ast::Shorthand::LIST
+                    .iter()
+                    .copied()
+                    .find(|&(_, x)| x == c)
+                    .map(|(s, _)| s),
+                codepoint: c as u32,
+                accent: typst::model::combining_accent(c).is_some(),
+                unicode_name: unicode_names2::name(c)
+                    .map(|s| s.to_string().to_title_case()),
+                alternates: symbol
+                    .variants()
+                    .filter(|(other, _)| other != &variant)
+                    .map(|(other, _)| complete(other))
+                    .collect(),
+            });
+        }
+    }
+
+    let title = match name {
+        "sym" => "General",
+        "emoji" => "Emoji",
+        _ => unreachable!(),
+    };
+
+    PageModel {
+        route: format!("{parent}{name}/"),
+        title: title.into(),
+        description: format!("Documentation for the `{name}` module."),
+        part: None,
+        body: BodyModel::Symbols(SymbolsModel {
+            name: title,
+            details: Html::markdown(resolver, details(name)),
+            list,
+        }),
+        children: vec![],
+    }
+}
+
+/// Data about a collection of functions.
+#[derive(Debug, Deserialize)]
+struct GroupData {
+    name: String,
+    title: String,
+    functions: Vec<String>,
+    description: String,
+}
+
+/// Extract a module from another module.
+#[track_caller]
+fn module<'a>(parent: &'a Module, name: &str) -> &'a Module {
+    match parent.scope().get(name) {
+        Some(Value::Module(module)) => module,
+        _ => panic!("module doesn't contain module `{name}`"),
+    }
+}
+
+/// Load YAML from a path.
+#[track_caller]
+fn yaml<T: DeserializeOwned>(path: &str) -> T {
+    let file = SRC.get_file(path).unwrap();
+    yaml::from_slice(file.contents()).unwrap()
+}
+
+/// Load details for an identifying key.
+#[track_caller]
+fn details(key: &str) -> &str {
+    DETAILS
+        .get(&yaml::Value::String(key.into()))
+        .and_then(|value| value.as_str())
+        .unwrap_or_else(|| panic!("missing details for {key}"))
+}
+
+/// Turn a title into an URL fragment.
+fn urlify(title: &str) -> String {
+    title
+        .chars()
+        .map(|c| c.to_ascii_lowercase())
+        .map(|c| match c {
+            'a'..='z' | '0'..='9' => c,
+            _ => '-',
+        })
+        .collect()
+}
+
+/// Extract the first line of documentation.
+fn oneliner(docs: &str) -> &str {
+    docs.lines().next().unwrap_or_default().into()
+}
+
+/// The order of types in the documentation.
+fn type_index(ty: &str) -> usize {
+    TYPE_ORDER.iter().position(|&v| v == ty).unwrap_or(usize::MAX)
+}
+
+const TYPE_ORDER: &[&str] = &[
+    "any",
+    "none",
+    "auto",
+    "boolean",
+    "integer",
+    "float",
+    "length",
+    "angle",
+    "ratio",
+    "relative length",
+    "fraction",
+    "color",
+    "string",
+    "regex",
+    "label",
+    "content",
+    "array",
+    "dictionary",
+    "function",
+    "arguments",
+    "dir",
+    "alignment",
+    "2d alignment",
+    "selector",
+    "stroke",
+];