Better documentation outlines

Cargo.lock

@@ -2312,6 +2312,7 @@ dependencies = [
  "pulldown-cmark",
  "serde",
  "serde_yaml",
+ "typed-arena",
  "typst",
  "typst-library",
  "unicode_names2",

docs/Cargo.toml

@@ -20,6 +20,7 @@ once_cell = "1"
 pulldown-cmark = "0.9"
 serde = { version = "1", features = ["derive"] }
 serde_yaml = "0.8"
+typed-arena = "2"
 unicode_names2 = "0.6.0"
 unscanny = "0.1"
 yaml-front-matter = "0.1"

docs/src/general/changelog.md

@@ -5,7 +5,7 @@ description: |
 ---
 
 # Changelog
-## April 26, 2023 (v0.3.0)
+## Version 0.3.0 (April 26, 2023) { #v0.3.0 }
 - **Breaking changes:**
   - Renamed a few symbols: What was previous `dot.op` is now just `dot` and the
     basic dot is `dot.basic`. The same applies to `ast` and `tilde`.
@@ -77,7 +77,7 @@ description: |
 
 <contributors from="v0.2.0" to="v0.3.0" />
 
-## April 11, 2023 (v0.2.0)
+## Version 0.2.0 (April 11, 2023) { #v0.2.0 }
 - **Breaking changes:**
   - Removed support for iterating over index and value in
     [for loops]($scripting/#loops). This is now handled via unpacking and
@@ -119,7 +119,7 @@ description: |
 
 <contributors from="v0.1.0" to="v0.2.0" />
 
-## April 04, 2023 (v0.1.0)
+## Version 0.1.0 (April 04, 2023) { #v0.1.0 }
 - **Breaking changes:**
   - When using the CLI, you now have to use subcommands:
     - `typst compile file.typ` or `typst c file.typ` to create a PDF

docs/src/general/community.md

@@ -22,7 +22,7 @@ welcome to connect with us on social media
 [LinkedIn](https://linkedin.com/company/typst), and
 [GitHub](https://github.com/typst)).
 
-## What to share?
+## What to share? { #want-to-share }
 For our community, we want to foster versatility and inclusivity.
 You are welcome to post about any topic that you think would interest other
 community members, but if you need a little inspiration, here are a few ideas:
@@ -34,7 +34,7 @@ community members, but if you need a little inspiration, here are a few ideas:
 - Share importable files or templates that you use to style your documents
 - Alert us of bugs you encounter while using Typst
 
-## Beta test
+## Beta test { #beta-test }
 We are starting a public beta test of our product on March 21st, 2023.
 The Typst compiler is still under active development and breaking changes can
 occur at any point. The compiler is developed in the open on
@@ -45,7 +45,7 @@ when new features become available in the preview. We'll also update you on the
 development progress of large features. A development tracker will become
 available on the documentation pages soon.
 
-## How to support Typst
+## How to support Typst { #support-typst }
 If you want to support Typst, there are multiple ways to do that! You can
 [contribute to the code](https://github.com/typst/typst) or
 [translate the strings in Typst](https://github.com/search?q=repo%3Atypst%2Ftypst+impl+LocalName+for&type=code)
@@ -54,7 +54,7 @@ to your native language if it's not supported yet. You can also help us by
 sponsorship tiers are available and all of them come with a set of goodies.
 No matter how you contribute, thank you for your support!
 
-## Community Rules
+## Community Rules { #rules }
 We want to make our community a safe and inclusive space for everyone.
 Therefore, we will not tolerate any sexual harassment, sexism, political
 attacks, derogatory language or personal insults, racism, doxing, and other
@@ -67,6 +67,6 @@ In addition, our [privacy policy](https://typst.app/privacy/) applies on all
 community spaces operated by us, such as the Discord server. Please also note
 that the terms of service and privacy policies of the respective services apply.
 
-## See you soon!
+## See you soon! { #see-you }
 Thanks again for learning more about Typst. We would be delighted to meet you on
 our [Discord server](https://discord.gg/2uDybryKPe)!

docs/src/guides/guide-for-latex-users.md

@@ -27,7 +27,7 @@ In the following, we will cover some of the most common questions a user
 switching from LaTeX will have when composing a document in Typst. If you prefer
 a step-by-step introduction to Typst, check out our [tutorial]($tutorial).
 
-## How do I create a new, empty document?
+## How do I create a new, empty document? { #getting-started }
 That's easy. You just create a new, empty text file (the file extension is
 `.typ`). No boilerplate is needed to get started. Simply start by writing your
 text. It will be set on an empty A4-sized page. If you are using the web app,
@@ -42,7 +42,7 @@ Here are two paragraphs. The
 output is shown to the right.
 ```
 
-## How do I create a section heading, emphasis, ...?
+## How do I create a section heading, emphasis, ...? { #elements }
 LaTeX uses the command `\section` to create a section heading. To nest deeper,
 you can use `\subsection`, `\subsubsection`, etc. Depending on your document
 class, there is also `\part` or `\chapter`.
@@ -108,7 +108,7 @@ To get a [numbered list]($func/enum) (`enumerate`) instead, use a `+` instead of
 the hyphen. For a [term list]($func/terms) (`description`), write
 `[/ Term: Description]` instead.
 
-## How do I use a command?
+## How do I use a command? { #commands }
 LaTeX heavily relies on commands (prefixed by backslashes). It uses these
 _macros_ to affect the typesetting process and to insert and manipulate content.
 Some commands accept arguments, most frequently they are enclosed in curly
@@ -148,7 +148,7 @@ A function call always involves the name of the function ([`rect`]($func/rect),
 [`range`]($func/range)) and then an argument list, even if it is empty. The
 argument list is enclosed in parentheses.
 
-### Arguments
+### Arguments { #arguments }
 A function can have multiple arguments. Some arguments are positional, i.e. you
 just provide the value: The function `[#lower("SCREAM")]` returns its argument
 in all-lowercase. Many functions use named arguments instead of positional
@@ -186,7 +186,7 @@ to LaTeX.
 #rect(fill: aqua)[Get started here!]
 ```
 
-### Data types
+### Data types { #data-types }
 You likely already noticed that the arguments have distinctive data types. Typst
 supports [many data types]($type). Below, there is a table with a few of the
 most important ones and how to write them:
@@ -209,7 +209,7 @@ define [variables]($scripting/#bindings) and do computations with them.
 
 In order to specify values of any of these types, you have to be in code mode!
 
-### Commands to affect the remaining document
+### Commands to affect the remaining document { #rules }
 In LaTeX, some commands like `\textbf{bold text}` are passed their argument in curly
 braces and only affect that argument whereas other commands like `\bfseries bold
 text` act as switches and change the appearance of all following content in the
@@ -252,7 +252,7 @@ element beyond what its arguments enable, you can completely redefine its
 appearance with a [show rule]($styling/#show-rules) (somewhat comparable to
 `\renewcommand`).
 
-## How do I load a document class?
+## How do I load a document class? { #templates }
 In LaTeX, you start your main `.tex` file with the `\documentclass{article}`
 command to define how your document is supposed to look. In that command, you
 may have replaced `article` with another value such as `report` and `amsart` to
@@ -385,7 +385,7 @@ You can also [create your own, custom templates.]($tutorial/making-a-template)
 They are shorter and more readable than the corresponding LaTeX `.sty` files by
 orders of magnitude, so give it a try!
 
-## How do I load packages?
+## How do I load packages? { #packages }
 Most things you load packages for in LaTeX are just included in Typst, no need
 to load or install anything. Below, we compiled a table with frequently loaded
 packages and their corresponding Typst functions.
@@ -418,7 +418,7 @@ Currently, there is no package manager for Typst, but we plan to build one so
 that you can easily use packages with tools and templates from the community and
 publish your own.
 
-## How do I input maths?
+## How do I input maths? { #maths }
 To enter math mode in Typst, just enclose your equation in dollar signs. You can
 enter display mode by putting spaces or newlines between the opening and closing
 dollar sign and the equation.
@@ -516,7 +516,7 @@ $ mat(
 ) $
 ```
 
-## How do I get the "LaTeX look?"
+## How do I get the "LaTeX look?" { #latex-look }
 Papers set in LaTeX have an unmistakeable look. This is mostly due to their
 font, Computer Modern, justification, narrow line spacing, and wide margins.
 
@@ -541,7 +541,7 @@ The example below
 This should be a good starting point! If you want to go further, why not create
 a reusable template?
 
-## What limitations does Typst currently have compared with LaTeX?
+## What limitations does Typst currently have compared with LaTeX? { #limitations }
 Although Typst can be a LaTeX replacement for many today, there are still
 features that Typst does not (yet) support. Here is a list of them which, where
 applicable, contains possible workarounds.

docs/src/guides/welcome.md

@@ -0,0 +1,11 @@
+---
+description: Guides for Typst.
+---
+
+# Guides
+Welcome to the Guides section! Here, you'll find helpful material for specific
+user groups or use cases. Currently, one guide is available: An introduction
+to Typst for LaTeX users. Feel free to propose other topics for guides!
+
+## List of Guides { #list-of-guides }
+- [Guide for LaTeX users]($guides/guide-for-latex-users)

docs/src/html.rs

@@ -3,6 +3,7 @@ use std::ops::Range;
 use comemo::Prehashed;
 use md::escape::escape_html;
 use pulldown_cmark as md;
+use typed_arena::Arena;
 use typst::diag::FileResult;
 use typst::font::{Font, FontBook};
 use typst::geom::{Point, Size};
@@ -22,17 +23,35 @@ pub struct Html {
     md: String,
     #[serde(skip)]
     description: Option<String>,
+    #[serde(skip)]
+    outline: Vec<OutlineItem>,
 }
 
 impl Html {
     /// Create HTML from a raw string.
     pub fn new(raw: String) -> Self {
-        Self { md: String::new(), raw, description: None }
+        Self {
+            md: String::new(),
+            raw,
+            description: None,
+            outline: vec![],
+        }
     }
 
     /// Convert markdown to HTML.
     #[track_caller]
     pub fn markdown(resolver: &dyn Resolver, md: &str) -> Self {
+        Self::markdown_with_id_base(resolver, md, "")
+    }
+
+    /// Convert markdown to HTML, preceding all fragment identifiers with the
+    /// `id_base`.
+    #[track_caller]
+    pub fn markdown_with_id_base(
+        resolver: &dyn Resolver,
+        md: &str,
+        id_base: &str,
+    ) -> Self {
         let mut text = md;
         let mut description = None;
         let document = YamlFrontMatter::parse::<Metadata>(md);
@@ -43,7 +62,8 @@ impl Html {
 
         let options = md::Options::ENABLE_TABLES | md::Options::ENABLE_HEADING_ATTRIBUTES;
 
-        let mut handler = Handler::new(resolver);
+        let ids = Arena::new();
+        let mut handler = Handler::new(resolver, id_base.into(), &ids);
         let iter = md::Parser::new_ext(text, options)
             .filter_map(|mut event| handler.handle(&mut event).then_some(event));
 
@@ -51,7 +71,12 @@ impl Html {
         md::html::push_html(&mut raw, iter);
         raw.truncate(raw.trim_end().len());
 
-        Html { md: text.into(), raw, description }
+        Html {
+            md: text.into(),
+            raw,
+            description,
+            outline: handler.outline,
+        }
     }
 
     /// The raw HTML.
@@ -72,6 +97,11 @@ impl Html {
         s.eat_if("<h1>").then(|| s.eat_until("</h1>"))
     }
 
+    /// The outline of the HTML.
+    pub fn outline(&self) -> Vec<OutlineItem> {
+        self.outline.clone()
+    }
+
     /// The description from the front matter.
     pub fn description(&self) -> Option<String> {
         self.description.clone()
@@ -93,14 +123,23 @@ struct Metadata {
 struct Handler<'a> {
     resolver: &'a dyn Resolver,
     lang: Option<String>,
+    outline: Vec<OutlineItem>,
+    id_base: String,
+    ids: &'a Arena<String>,
 }
 
 impl<'a> Handler<'a> {
-    fn new(resolver: &'a dyn Resolver) -> Self {
+    fn new(resolver: &'a dyn Resolver, id_base: String, ids: &'a Arena<String>) -> Self {
-        Self { resolver, lang: None }
+        Self {
+            resolver,
+            lang: None,
+            outline: vec![],
+            id_base,
+            ids,
+        }
     }
 
-    fn handle(&mut self, event: &mut md::Event) -> bool {
+    fn handle(&mut self, event: &mut md::Event<'a>) -> bool {
         let lang = self.lang.take();
         match event {
             // Rewrite Markdown images.
@@ -117,7 +156,19 @@ impl<'a> Handler<'a> {
                 *html = buf.into();
             }
 
-            // Rewrite contributor sectinos.
+            // Register HTML headings for the outline.
+            md::Event::Start(md::Tag::Heading(level, Some(id), _)) => {
+                self.handle_heading(id, level);
+            }
+
+            // Also handle heading closings.
+            md::Event::End(md::Tag::Heading(level, Some(_), _)) => {
+                if *level > md::HeadingLevel::H1 && !self.id_base.is_empty() {
+                    nest_heading(level);
+                }
+            }
+
+            // Rewrite contributor sections.
             md::Event::Html(html) if html.starts_with("<contributors") => {
                 let from = html_attr(html, "from").unwrap();
                 let to = html_attr(html, "to").unwrap();
@@ -184,6 +235,36 @@ impl<'a> Handler<'a> {
         }
     }
 
+    fn handle_heading(&mut self, id: &mut &'a str, level: &mut md::HeadingLevel) {
+        if *level == md::HeadingLevel::H1 {
+            return;
+        }
+
+        // Special case for things like "v0.3.0".
+        let name = if id.starts_with('v') && id.contains('.') {
+            id.to_string()
+        } else {
+            id.to_title_case()
+        };
+
+        let mut children = &mut self.outline;
+        let mut depth = *level as usize;
+        while depth > 2 {
+            if !children.is_empty() {
+                children = &mut children.last_mut().unwrap().children;
+            }
+            depth -= 1;
+        }
+
+        // Put base before id.
+        if !self.id_base.is_empty() {
+            nest_heading(level);
+            *id = self.ids.alloc(format!("{}-{id}", self.id_base)).as_str();
+        }
+
+        children.push(OutlineItem { id: id.to_string(), name, children: vec![] });
+    }
+
     fn handle_link(&self, link: &str) -> Option<String> {
         if link.starts_with('#') || link.starts_with("http") {
             return Some(link.into());
@@ -205,6 +286,7 @@ impl<'a> Handler<'a> {
             "$types" => "/docs/reference/types/",
             "$type" => "/docs/reference/types/",
             "$func" => "/docs/reference/",
+            "$guides" => "/docs/guides/",
             "$changelog" => "/docs/changelog/",
             "$community" => "/docs/community/",
             _ => panic!("unknown link root: {root}"),
@@ -216,7 +298,7 @@ impl<'a> Handler<'a> {
             let ty = parts.next()?;
             let method = parts.next()?;
             route.push_str(ty);
-            route.push_str("/#methods--");
+            route.push_str("/#methods-");
             route.push_str(method);
         } else if root == "$func" {
             let mut parts = rest.split('.');
@@ -237,7 +319,7 @@ impl<'a> Handler<'a> {
                 route.push_str("/#");
                 route.push_str(info.name);
                 if let Some(param) = param {
-                    route.push_str("-parameters--");
+                    route.push_str("-parameters-");
                     route.push_str(param);
                 } else {
                     route.push_str("-summary");
@@ -246,7 +328,7 @@ impl<'a> Handler<'a> {
                 route.push_str(name);
                 route.push('/');
                 if let Some(param) = param {
-                    route.push_str("#parameters--");
+                    route.push_str("#parameters-");
                     route.push_str(param);
                 }
             }
@@ -347,6 +429,18 @@ fn html_attr_range(html: &str, attr: &str) -> Option<Range<usize>> {
     Some(offset..offset + len)
 }
 
+/// Increase the nesting level of a Markdown heading.
+fn nest_heading(level: &mut md::HeadingLevel) {
+    *level = match &level {
+        md::HeadingLevel::H1 => md::HeadingLevel::H2,
+        md::HeadingLevel::H2 => md::HeadingLevel::H3,
+        md::HeadingLevel::H3 => md::HeadingLevel::H4,
+        md::HeadingLevel::H4 => md::HeadingLevel::H5,
+        md::HeadingLevel::H5 => md::HeadingLevel::H6,
+        v => **v,
+    };
+}
+
 /// World for example compilations.
 struct DocWorld(Source);
 

docs/src/lib.rs

@@ -54,9 +54,9 @@ static LIBRARY: Lazy<Prehashed<Library>> = Lazy::new(|| {
 pub fn provide(resolver: &dyn Resolver) -> Vec<PageModel> {
     vec![
         markdown_page(resolver, "/docs/", "general/overview.md").with_route("/docs/"),
-        tutorial_page(resolver),
+        tutorial_pages(resolver),
-        reference_page(resolver),
+        reference_pages(resolver),
-        markdown_page(resolver, "/docs/", "general/guide-for-latex-users.md"),
+        guides_pages(resolver),
         markdown_page(resolver, "/docs/", "general/changelog.md"),
         markdown_page(resolver, "/docs/", "general/community.md"),
     ]
@@ -99,6 +99,14 @@ impl PageModel {
     }
 }
 
+/// An element in the "On This Page" outline.
+#[derive(Debug, Clone, Serialize)]
+pub struct OutlineItem {
+    id: String,
+    name: String,
+    children: Vec<Self>,
+}
+
 /// Details about the body of a documentation page.
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
@@ -113,7 +121,7 @@ pub enum BodyModel {
 }
 
 /// Build the tutorial.
-fn tutorial_page(resolver: &dyn Resolver) -> PageModel {
+fn tutorial_pages(resolver: &dyn Resolver) -> PageModel {
     let mut page = markdown_page(resolver, "/docs/", "tutorial/welcome.md");
     page.children = SRC
         .get_dir("tutorial")
@@ -125,8 +133,16 @@ fn tutorial_page(resolver: &dyn Resolver) -> PageModel {
     page
 }
 
+/// Build the guides section.
+fn guides_pages(resolver: &dyn Resolver) -> PageModel {
+    let mut page = markdown_page(resolver, "/docs/", "guides/welcome.md");
+    page.children =
+        vec![markdown_page(resolver, "/docs/guides/", "guides/guide-for-latex-users.md")];
+    page
+}
+
 /// Build the reference.
-fn reference_page(resolver: &dyn Resolver) -> PageModel {
+fn reference_pages(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")
@@ -164,6 +180,7 @@ fn markdown_page(
         title,
         description: html.description().unwrap(),
         part: None,
+        outline: html.outline(),
         body: BodyModel::Html(html),
         children: vec![],
     }
@@ -200,6 +217,12 @@ fn category_page(resolver: &dyn Resolver, category: &str) -> PageModel {
         _ => &LIBRARY.global,
     };
 
+    let parents: &[&str] = match category {
+        "math" => &[],
+        "calculate" => &["calc"],
+        _ => &[],
+    };
+
     let grouped = match category {
         "math" => GROUPS.as_slice(),
         _ => &[],
@@ -222,7 +245,7 @@ fn category_page(resolver: &dyn Resolver, category: &str) -> PageModel {
             continue;
         }
 
-        let subpage = function_page(resolver, &route, func, info);
+        let subpage = function_page(resolver, &route, func, info, parents);
         items.push(CategoryItem {
             name: info.name.into(),
             route: subpage.route.clone(),
@@ -235,11 +258,21 @@ fn category_page(resolver: &dyn Resolver, category: &str) -> PageModel {
     // Add grouped functions.
     for group in grouped {
         let mut functions = vec![];
+        let mut outline = vec![OutlineItem {
+            id: "summary".into(),
+            name: "Summary".into(),
+            children: 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 func = func_model(resolver, func, info, &[], info.name);
+            let id = urlify(&func.path.join("-"));
+            let children = func_outline(&func, &id, false);
+            outline.push(OutlineItem { id, name: func.display.into(), children });
+            functions.push(func);
         }
 
         let route = format!("{}{}/", route, group.name);
@@ -249,13 +282,16 @@ fn category_page(resolver: &dyn Resolver, category: &str) -> PageModel {
             oneliner: oneliner(&group.description).into(),
             code: false,
         });
+
         children.push(PageModel {
             route,
-            title: group.title.clone(),
+            title: group.display.clone(),
             description: format!("Documentation for {} group of functions.", group.name),
             part: None,
+            outline,
             body: BodyModel::Funcs(FuncsModel {
                 name: group.name.clone(),
+                display: group.display.clone(),
                 details: Html::markdown(resolver, &group.description),
                 functions,
             }),
@@ -281,28 +317,47 @@ fn category_page(resolver: &dyn Resolver, category: &str) -> PageModel {
     }
 
     let name = category.to_title_case();
+    let kind = match category {
+        "symbols" => "Modules",
+        _ => "Functions",
+    };
+
     PageModel {
         route,
         title: name.clone(),
         description: format!("Documentation for functions related to {name} in Typst."),
         part: None,
+        outline: category_outline(kind),
         body: BodyModel::Category(CategoryModel {
             name,
             details: Html::markdown(resolver, details(category)),
-            kind: match category {
+            kind,
-                "symbols" => "Modules",
-                _ => "Functions",
-            },
             items,
         }),
         children,
     }
 }
 
+/// Produce an outline for a category page.
+fn category_outline(kind: &str) -> Vec<OutlineItem> {
+    vec![
+        OutlineItem {
+            id: "summary".into(),
+            name: "Summary".into(),
+            children: vec![],
+        },
+        OutlineItem {
+            id: urlify(kind),
+            name: kind.into(),
+            children: vec![],
+        },
+    ]
+}
+
 /// Details about a function.
 #[derive(Debug, Serialize)]
 pub struct FuncModel {
-    pub name: &'static str,
+    pub path: Vec<&'static str>,
     pub display: &'static str,
     pub oneliner: &'static str,
     pub element: bool,
@@ -310,12 +365,14 @@ pub struct FuncModel {
     pub params: Vec<ParamModel>,
     pub returns: Vec<&'static str>,
     pub methods: Vec<MethodModel>,
+    pub scope: Vec<Self>,
 }
 
 /// Details about a group of functions.
 #[derive(Debug, Serialize)]
 pub struct FuncsModel {
     pub name: String,
+    pub display: String,
     pub details: Html,
     pub functions: Vec<FuncModel>,
 }
@@ -326,33 +383,105 @@ fn function_page(
     parent: &str,
     func: &Func,
     info: &FuncInfo,
+    parents: &[&'static str],
 ) -> PageModel {
+    let model = func_model(resolver, func, info, parents, "");
     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)),
+        outline: func_outline(&model, "", true),
+        body: BodyModel::Func(model),
         children: vec![],
     }
 }
 
 /// Produce a function's model.
-fn func_model(resolver: &dyn Resolver, func: &Func, info: &FuncInfo) -> FuncModel {
+fn func_model(
+    resolver: &dyn Resolver,
+    func: &Func,
+    info: &FuncInfo,
+    parents: &[&'static str],
+    id_base: &str,
+) -> FuncModel {
     let mut s = unscanny::Scanner::new(info.docs);
     let docs = s.eat_until("\n## Methods").trim();
+
+    let mut path = parents.to_vec();
+    let mut name = info.name;
+    for parent in parents.iter().rev() {
+        name = name
+            .strip_prefix(parent)
+            .or(name.strip_prefix(parent.strip_suffix('s').unwrap_or(parent)))
+            .unwrap_or(name);
+    }
+    path.push(name);
+
+    let scope = info
+        .scope
+        .iter()
+        .filter_map(|(_, value)| {
+            let Value::Func(func) = value else { return None };
+            let info = func.info().unwrap();
+            Some(func_model(resolver, func, info, &path, id_base))
+        })
+        .collect();
+
     FuncModel {
-        name: info.name,
+        path,
         display: info.display,
         oneliner: oneliner(docs),
         element: func.element().is_some(),
-        details: Html::markdown(resolver, docs),
+        details: Html::markdown_with_id_base(resolver, docs, id_base),
         params: info.params.iter().map(|param| param_model(resolver, param)).collect(),
         returns: info.returns.clone(),
         methods: method_models(resolver, info.docs),
+        scope,
     }
 }
 
+/// Produce an outline for a function page.
+fn func_outline(model: &FuncModel, base: &str, summary: bool) -> Vec<OutlineItem> {
+    let mut outline = vec![];
+
+    if summary {
+        outline.push(OutlineItem {
+            id: "summary".into(),
+            name: "Summary".into(),
+            children: vec![],
+        });
+    }
+
+    outline.extend(model.details.outline());
+
+    if !model.params.is_empty() {
+        let join = if base.is_empty() { "" } else { "-" };
+        outline.push(OutlineItem {
+            id: format!("{base}{join}parameters"),
+            name: "Parameters".into(),
+            children: model
+                .params
+                .iter()
+                .map(|param| OutlineItem {
+                    id: format!("{base}{join}parameters-{}", urlify(param.name)),
+                    name: param.name.into(),
+                    children: vec![],
+                })
+                .collect(),
+        });
+    }
+
+    for func in &model.scope {
+        let id = urlify(&func.path.join("-"));
+        let children = func_outline(func, &id, false);
+        outline.push(OutlineItem { id, name: func.display.into(), children })
+    }
+
+    outline.extend(methods_outline(&model.methods));
+    outline
+}
+
 /// Details about a function parameter.
 #[derive(Debug, Serialize)]
 pub struct ParamModel {
@@ -469,6 +598,7 @@ fn types_page(resolver: &dyn Resolver, parent: &str) -> PageModel {
             title: model.name.to_title_case(),
             description: format!("Documentation for the `{}` type.", model.name),
             part: None,
+            outline: type_outline(&model),
             body: BodyModel::Type(model),
             children: vec![],
         });
@@ -479,6 +609,7 @@ fn types_page(resolver: &dyn Resolver, parent: &str) -> PageModel {
         title: "Types".into(),
         description: "Documentation for Typst's built-in types.".into(),
         part: None,
+        outline: category_outline("Types"),
         body: BodyModel::Category(CategoryModel {
             name: "Types".into(),
             details: Html::markdown(resolver, details("types")),
@@ -604,6 +735,48 @@ fn method_model(resolver: &dyn Resolver, part: &'static str) -> MethodModel {
     }
 }
 
+/// Produce an outline for a type page.
+fn type_outline(model: &TypeModel) -> Vec<OutlineItem> {
+    let mut outline = vec![OutlineItem {
+        id: "summary".into(),
+        name: "Summary".into(),
+        children: vec![],
+    }];
+
+    outline.extend(methods_outline(&model.methods));
+    outline
+}
+
+/// Produce an outline for a type's method.
+fn methods_outline(methods: &[MethodModel]) -> Option<OutlineItem> {
+    (!methods.is_empty()).then(|| OutlineItem {
+        id: "methods".into(),
+        name: "Methods".into(),
+        children: methods.iter().map(method_outline).collect(),
+    })
+}
+
+/// Produce an outline for a type's method.
+fn method_outline(model: &MethodModel) -> OutlineItem {
+    OutlineItem {
+        id: format!("methods-{}", urlify(model.name)),
+        name: model.name.into(),
+        children: model
+            .params
+            .iter()
+            .map(|param| OutlineItem {
+                id: format!(
+                    "methods-{}-parameters-{}",
+                    urlify(model.name),
+                    urlify(param.name)
+                ),
+                name: param.name.into(),
+                children: vec![],
+            })
+            .collect(),
+    }
+}
+
 /// A collection of symbols.
 #[derive(Debug, Serialize)]
 pub struct SymbolsModel {
@@ -671,6 +844,7 @@ fn symbol_page(resolver: &dyn Resolver, parent: &str, name: &str) -> PageModel {
         title: title.into(),
         description: format!("Documentation for the `{name}` module."),
         part: None,
+        outline: vec![],
         body: BodyModel::Symbols(SymbolsModel {
             name: title,
             details: Html::markdown(resolver, details(name)),
@@ -684,7 +858,7 @@ fn symbol_page(resolver: &dyn Resolver, parent: &str, name: &str) -> PageModel {
 #[derive(Debug, Deserialize)]
 struct GroupData {
     name: String,
-    title: String,
+    display: String,
     functions: Vec<String>,
     description: String,
 }

docs/src/reference/groups.yml

@@ -1,5 +1,5 @@
 - name: variants
-  title: Variants
+  display: Variants
   functions: ["serif", "sans", "frak", "mono", "bb", "cal"]
   description: |
     Alternate typefaces within formulas.
@@ -8,7 +8,7 @@
     math fonts contain multiple variants of each letter.
 
 - name: styles
-  title: Styles
+  display: Styles
   functions: ["upright", "italic", "bold"]
   description: |
     Alternate letterforms within formulas.
@@ -17,7 +17,7 @@
     math fonts contain multiple variants of each letter.
 
 - name: underover
-  title: Under/Over
+  display: Under/Over
   functions: [
     "underline",
     "overline",
@@ -33,12 +33,12 @@
     below or above themselves.
 
 - name: roots
-  title: Roots
+  display: Roots
   functions: ["root", "sqrt"]
   description: Square and non-square roots.
 
 - name: attach
-  title: Attach
+  display: Attach
   functions: ["attach", "scripts", "limits"]
   description: |
     Subscript, superscripts, and limits.
@@ -50,7 +50,7 @@
     the `scripts` and `limits` functions.
 
 - name: lr
-  title: Left/Right
+  display: Left/Right
   functions: ["lr", "abs", "norm", "floor", "ceil"]
   description: |
     Delimiter matching.

docs/src/reference/welcome.md

@@ -10,14 +10,14 @@ syntax, concepts, types, and functions. If you are completely new to Typst, we
 recommend starting with the [tutorial]($tutorial) and then coming back to
 the reference to learn more about Typst's features as you need them.
 
-## Language
+## Language { #language }
 The reference starts with a language part that gives an overview over [Typst's
 syntax]($syntax) and contains information about concepts involved in
 [styling documents,]($styling) using
 [Typst's scripting capabilities,]($scripting) and a detailed documentation of
 all [data types]($types) in Typst.
 
-## Functions
+## Functions { #functions }
 The second part includes chapters on all functions used to insert, style, transform,
 and layout content in Typst documents. Each function is documented with a
 description of its purpose, a list of its parameters, and examples of how to use

docs/src/tutorial/1-writing.md

@@ -67,7 +67,7 @@ the first item of the list above by indenting it.
 + The geology
 ```
 
-## Adding a figure
+## Adding a figure { #figure }
 You think that your report would benefit from a figure. Let's add one. Typst
 supports images in the formats PNG, JPEG, GIF, and SVG. To add an image file to
 your project, first open the _file panel_ by clicking the box icon in the left
@@ -174,7 +174,7 @@ On the contrary, strings work wherever content is expected because text is a
 valid kind of content.
 </div>
 
-## Adding a bibliography
+## Adding a bibliography { #bibliography }
 As you write up your report, you need to back up some of your claims. You can
 add a bibliography to your document with the
 [`bibliography`]($func/bibliography) function. This function expects a path
@@ -200,7 +200,7 @@ established in @glacier-melt.
 #bibliography("works.bib")
 ```
 
-## Maths
+## Maths { #maths }
 After fleshing out the methods section, you move on to the meat of the document:
 Your equations. Typst has built-in mathematical typesetting and uses its own
 math notation. Let's start with a simple equation. We wrap it in `[$]` signs
@@ -293,7 +293,7 @@ This notation is also available in markup mode, but the symbol name must be
 preceded with `#sym.` there. See the [symbols section]($category/symbols/sym)
 for a list of all available symbols.
 
-## Review
+## Review { #review }
 You have now seen how to write a basic document in Typst. You learned how to
 emphasize text, write lists, insert images, align content, and typeset
 mathematical expressions. You also learned about Typst's functions. There are

docs/src/tutorial/2-formatting.md

@@ -9,7 +9,7 @@ that you are using a new typesetting system, and you want your report to fit in
 with the other student's submissions. In this chapter, we will see how to format
 your report using Typst's styling system.
 
-## Set rules
+## Set rules { #set-rules }
 As we have seen in the previous chapter, Typst has functions that _insert_
 content (e.g. the [`image`]($func/image) function) and others that _manipulate_
 content that they received as arguments (e.g. the [`align`]($func/align)
@@ -70,7 +70,7 @@ for some of the parameters of a function for all future
 uses of that function.
 </div>
 
-## The autocomplete panel
+## The autocomplete panel { #autocomplete }
 If you followed along and tried a few things in the app, you might have noticed
 that always after you enter a `#` character, a panel pops up to show you the
 available functions, and, within an argument list, the available parameters.
@@ -84,7 +84,7 @@ what they do.
 
 ![Autocomplete panel](2-formatting-autocomplete.png)
 
-## Set up the page
+## Set up the page { #page-setup }
 Back to set rules: When writing a rule, you choose the function depending on
 what type of element you want to style. Here is a list of some functions that
 are commonly used in set rules:
@@ -175,7 +175,7 @@ Finally, we have bottom aligned our image by adding a vertical alignment to our
 center alignment. Vertical and horizontal alignments can be combined with the
 `{+}` operator to yield a 2D alignment.
 
-## A hint of sophistication
+## A hint of sophistication { #sophistication }
 To structure our document more clearly, we now want to number our headings. We
 can do this by setting the `numbering` parameter of the
 [`heading`]($func/heading) function.
@@ -228,7 +228,7 @@ markup above. Other markup elements work similarly, they are only
 _syntax sugar_ for the corresponding function calls.
 </div>
 
-## Show rules
+## Show rules { #show-rules }
 You are already pretty happy with how this turned out. But one last thing needs
 to be fixed: The report you are writing is intended for a larger project and
 that project's name should always be accompanied by a logo, even in prose.
@@ -272,7 +272,7 @@ expects code instead of markup, the leading `#` is not needed to access
 functions, keywords, and variables. This can be observed in parameter lists,
 function definitions, and [code blocks]($scripting).
 
-## Review
+## Review { #review }
 You now know how to apply basic formatting to your Typst documents. You learned
 how to set the font, justify your paragraphs, change the page dimensions, and
 add numbering to your headings with set rules. You also learned how to use a

docs/src/tutorial/3-advanced.md

@@ -26,7 +26,7 @@ Now, your supervisor can also edit the project and you can both see the changes
 in real time. You can join our [Discord server](https://discord.gg/2uDybryKPe)
 to find others with preview access and try teams with them!
 
-## The conference guidelines
+## The conference guidelines { #guidelines }
 The layout guidelines are available on the conference website. Let's take a look
 at them:
 
@@ -46,7 +46,7 @@ at them:
 We already know how to do many of these things, but for some of them, we'll need
 to learn some new tricks.
 
-## Writing the right set rules
+## Writing the right set rules { #set-rules }
 Let's start by writing some set rules for the document.
 
 ```example
@@ -84,7 +84,7 @@ setting into to `{"1"}`, Typst only displays the bare page number. Setting it to
 surrounded by parentheses. And we could even have provided a completely custom
 function here to format things to our liking.
 
-## Creating a title and abstract
+## Creating a title and abstract { #title-and-abstract }
 Now, let's add a title and an abstract. We'll start with the title. We center
 align it and increase its font weight by enclosing it in `[*stars*]`.
 
@@ -246,7 +246,7 @@ After we bound the content to the `title` variable, we can use it in functions
 and also within markup (prefixed by `#`, like functions). This way, if we decide
 on another title, we can easily change it in one place.
 
-## Adding columns and headings
+## Adding columns and headings { #columns-and-headings }
 The paper above unfortunately looks like a wall of lead. To fix that, let's add
 some headings and switch our paper to a two-column layout. The
 [`columns`]($func/columns) function takes a number and content, and layouts the
@@ -493,7 +493,7 @@ the conference! The finished paper looks like this:
   style="box-shadow: 0 4px 12px rgb(89 85 101 / 20%); width: 500px; max-width: 100%; display: block; margin: 24px auto;"
 >
 
-## Review
+## Review { #review }
 You have now learned how to create headers and footers, how to use functions and
 scopes to locally override styles, how to create more complex layouts with the [`grid`]($func/grid) function and how to write show rules for individual functions, and the whole document. You also learned how to use the
 [`where` selector]($styling/#show-rules) to filter the headings by their level.

docs/src/tutorial/4-template.md

@@ -12,7 +12,7 @@ you created in the previous chapter and turn it into a reusable template. In
 this chapter you will learn how to create a template that you and your team can
 use with just one show rule. Let's get started!
 
-## A toy template
+## A toy template { #toy-template }
 In Typst, templates are functions in which you can wrap your whole document. To
 learn how to do that, let's first review how to write your very own functions.
 They can do anything you want them to, so why not go a bit crazy?
@@ -60,7 +60,7 @@ wrapped it around it. This is not especially useful with this particular
 function, but when combined with set rules and named arguments, it can be very
 powerful.
 
-## Embedding set and show rules
+## Embedding set and show rules { #set-and-show-rules }
 To apply some set and show rules to our template, we can use `set` and `show`
 within a content block in our function and then insert the document into
 that content block.
@@ -159,7 +159,7 @@ Also note where the title comes from: We previously had it inside of a variable.
 Now, we are receiving it as the first parameter of the template function.
 Thus, we must specify it in the show rule where we call the template.
 
-## Templates with named arguments
+## Templates with named arguments { #named-arguments }
 Our paper in the previous chapter had a title and an author list. Let's add these
 things to our template. In addition to the title, we want our template to accept
 a list of authors with their affiliations and the paper's abstract. To keep
@@ -253,7 +253,7 @@ The resulting template function looks like this:
 }
 ```
 
-## A separate file
+## A separate file { #separate-file }
 Most of the time, a template is specified in a different file and then imported
 into the document. This way, the main file you write in is kept clutter free and
 your template is easily reused. Create a new text file in the file panel by
@@ -365,7 +365,7 @@ conference! Why not share it on
 [Typst's Discord server](https://discord.gg/2uDybryKPe) so that others can use
 it too?
 
-## Review
+## Review { #review }
 Congratulations, you have completed Typst's Tutorial! In this section, you have
 learned how to define your own functions and how to create and apply templates
 that define reusable document styles. You've made it far and learned a lot. You

docs/src/tutorial/welcome.md

@@ -14,7 +14,7 @@ with the steps below. The app gives you instant preview, syntax highlighting and
 helpful autocompletions. Alternatively, you can follow along in your local text
 editor with the [open-source CLI](https://github.com/typst/typst).
 
-## When to use Typst
+## When to use Typst { #when-typst }
 Before we get started, let's check what Typst is and when to use it. Typst is a
 markup language for typesetting documents. It is designed to be easy to learn,
 fast, and versatile. Typst takes text files with markup in them and outputs
@@ -27,7 +27,7 @@ in the math, physics, and engineering fields. Finally, due to its strong styling
 and automation features, it is an excellent choice for any set of documents that
 share a common style, such as a book series.
 
-## What you will learn
+## What you will learn { #learnings }
 This tutorial has four chapters. Each chapter builds on the previous one. Here
 is what you will learn in each of them:
 

library/src/compute/calc.rs

@@ -52,7 +52,7 @@ pub fn module() -> Module {
 
 /// Calculate the absolute value of a numeric value.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.abs(-5) \
 /// #calc.abs(5pt - 2cm) \
@@ -86,7 +86,7 @@ cast_from_value! {
 
 /// Raise a value to some exponent.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.pow(2, 3)
 /// ```
@@ -133,7 +133,7 @@ pub fn pow(
 
 /// Calculate the square root of a number.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.sqrt(16) \
 /// #calc.sqrt(2.5)
@@ -158,7 +158,7 @@ pub fn sqrt(
 /// When called with an integer or a float, they will be interpreted as
 /// radians.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #assert(calc.sin(90deg) == calc.sin(-270deg))
 /// #calc.sin(1.5) \
@@ -185,7 +185,7 @@ pub fn sin(
 /// When called with an integer or a float, they will be interpreted as
 /// radians.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.cos(90deg) \
 /// #calc.cos(1.5) \
@@ -212,7 +212,7 @@ pub fn cos(
 /// When called with an integer or a float, they will be interpreted as
 /// radians.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.tan(1.5) \
 /// #calc.tan(90deg)
@@ -235,7 +235,7 @@ pub fn tan(
 
 /// Calculate the arcsine of a number.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.asin(0) \
 /// #calc.asin(1)
@@ -258,7 +258,7 @@ pub fn asin(
 
 /// Calculate the arccosine of a number.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.acos(0) \
 /// #calc.acos(1)
@@ -281,7 +281,7 @@ pub fn acos(
 
 /// Calculate the arctangent of a number.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.atan(0) \
 /// #calc.atan(1)
@@ -302,7 +302,7 @@ pub fn atan(
 ///
 /// The arguments are `(x, y)`, not `(y, x)`.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.atan2(1, 1) \
 /// #calc.atan2(-2, -3)
@@ -325,7 +325,7 @@ pub fn atan2(
 ///
 /// When called with an integer or a float, they will be interpreted as radians.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.sinh(0) \
 /// #calc.sinh(45deg)
@@ -350,7 +350,7 @@ pub fn sinh(
 ///
 /// When called with an integer or a float, they will be interpreted as radians.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.cosh(0) \
 /// #calc.cosh(45deg)
@@ -375,7 +375,7 @@ pub fn cosh(
 ///
 /// When called with an integer or a float, they will be interpreted as radians.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.tanh(0) \
 /// #calc.tanh(45deg)
@@ -400,7 +400,7 @@ pub fn tanh(
 ///
 /// If the base is not specified, the logarithm is calculated in base 10.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.log(100)
 /// ```
@@ -443,7 +443,7 @@ pub fn log(
 
 /// Calculate the factorial of a number.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.fact(5)
 /// ```
@@ -481,7 +481,7 @@ fn factorial_range(start: u64, end: u64) -> Option<i64> {
 
 /// Calculate a permutation.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.perm(10, 5)
 /// ```
@@ -509,7 +509,7 @@ pub fn perm(
 
 /// Calculate a binomial coefficient.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.binom(10, 5)
 /// ```
@@ -554,7 +554,7 @@ fn binomial(n: u64, k: u64) -> Option<i64> {
 
 /// Calculate the greatest common divisor of two integers.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.gcd(7, 42)
 /// ```
@@ -586,7 +586,7 @@ fn calculate_gcd(mut a: i64, mut b: i64) -> i64 {
 
 /// Calculate the least common multiple of two integers.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.lcm(96, 13)
 /// ```
@@ -622,7 +622,7 @@ fn calculate_lcm(a: i64, b: i64) -> Option<i64> {
 ///
 /// If the number is already an integer, it is returned unchanged.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #assert(calc.floor(3.14) == 3)
 /// #assert(calc.floor(3) == 3)
@@ -647,7 +647,7 @@ pub fn floor(
 ///
 /// If the number is already an integer, it is returned unchanged.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #assert(calc.ceil(3.14) == 4)
 /// #assert(calc.ceil(3) == 3)
@@ -672,7 +672,7 @@ pub fn ceil(
 ///
 /// If the number is already an integer, it is returned unchanged.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #assert(calc.trunc(3) == 3)
 /// #assert(calc.trunc(-3.7) == -3)
@@ -697,7 +697,7 @@ pub fn trunc(
 ///
 /// If the number is an integer, it returns `0`.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #assert(calc.fract(3) == 0)
 /// #calc.fract(-3.1)
@@ -721,7 +721,7 @@ pub fn fract(
 ///
 /// Optionally, a number of decimal places can be specified.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #assert(calc.round(3.14) == 3)
 /// #assert(calc.round(3.5) == 4)
@@ -752,7 +752,7 @@ pub fn round(
 
 /// Clamp a number between a minimum and maximum value.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #assert(calc.clamp(5, 0, 10) == 5)
 /// #assert(calc.clamp(5, 6, 10) == 6)
@@ -779,7 +779,7 @@ pub fn clamp(
 
 /// Determine the minimum of a sequence of values.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.min(1, -3, -5, 20, 3, 6) \
 /// #calc.min("typst", "in", "beta")
@@ -800,7 +800,7 @@ pub fn min(
 
 /// Determine the maximum of a sequence of values.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.max(1, -3, -5, 20, 3, 6) \
 /// #calc.max("typst", "in", "beta")
@@ -851,7 +851,7 @@ fn minmax(
 
 /// Determine whether an integer is even.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.even(4) \
 /// #calc.even(5) \
@@ -871,7 +871,7 @@ pub fn even(
 
 /// Determine whether an integer is odd.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.odd(4) \
 /// #calc.odd(5) \
@@ -891,7 +891,7 @@ pub fn odd(
 
 /// Calculate the remainder of two numbers.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.rem(20, 6) \
 /// #calc.rem(1.75, 0.5)
@@ -936,7 +936,7 @@ pub fn mod_(
 
 /// Calculate the quotient of two numbers.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #calc.quo(14, 5) \
 /// #calc.quo(3.46, 0.5)

library/src/compute/construct.rs

@@ -11,7 +11,7 @@ use crate::prelude::*;
 /// - Floats are floored to the next 64-bit integer.
 /// - Strings are parsed in base 10.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #int(false) \
 /// #int(true) \
@@ -49,7 +49,7 @@ cast_from_value! {
 /// - Strings are parsed in base 10 to the closest 64-bit float.
 ///   Exponential notation is supported.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #float(false) \
 /// #float(true) \
@@ -84,7 +84,7 @@ cast_from_value! {
 
 /// Create a grayscale color.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #for x in range(250, step: 50) {
 ///   box(square(fill: luma(x)))
@@ -110,7 +110,7 @@ pub fn luma(
 /// render them correctly, the PDF export does not handle them properly at the
 /// moment. This will be fixed in the future.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #square(fill: rgb("#b1f2eb"))
 /// #square(fill: rgb(87, 127, 230))
@@ -190,7 +190,7 @@ cast_from_value! {
 /// to RGB for display preview might differ from how your printer reproduces
 /// the color.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #square(
 ///   fill: cmyk(27%, 0%, 3%, 5%)
@@ -228,7 +228,7 @@ cast_from_value! {
 
 /// Create a custom symbol with modifiers.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #let envelope = symbol(
 ///   "🖂",
@@ -294,7 +294,7 @@ cast_from_value! {
 /// - Floats are formatted in base 10 and never in exponential notation.
 /// - From labels the name is extracted.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #str(10) \
 /// #str(2.7) \
@@ -330,7 +330,7 @@ cast_from_value! {
 /// that is not a space. Then, the element can be [referenced]($func/ref) and
 /// styled through the label.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #show <a>: set text(blue)
 /// #show label("b"): set text(red)
@@ -339,7 +339,7 @@ cast_from_value! {
 /// *Strong* #label("b")
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: You can create a label by enclosing
 /// its name in angle brackets. This works both in markup and code.
 ///
@@ -363,7 +363,7 @@ pub fn label(
 /// [See here](https://docs.rs/regex/latest/regex/#syntax) for a specification
 /// of the supported syntax.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// // Works with show rules.
 /// #show regex("\d+"): set text(red)
@@ -401,7 +401,7 @@ pub fn regex(
 /// the range. If you pass two, they describe the `start` and `end` of the
 /// range.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #range(5) \
 /// #range(2, 5) \

library/src/compute/data.rs

@@ -6,7 +6,7 @@ use crate::prelude::*;
 ///
 /// The file will be read and returned as a string.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #let text = read("data.html")
 ///
@@ -38,7 +38,7 @@ pub fn read(
 /// rows will be collected into a single array. Header rows will not be
 /// stripped.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #let results = csv("data.csv")
 ///
@@ -138,7 +138,7 @@ fn format_csv_error(error: csv::Error, line: usize) -> EcoString {
 /// The JSON files in the example contain objects with the keys `temperature`,
 /// `unit`, and `weather`.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #let forecast(day) = block[
 ///   #box(square(
@@ -218,7 +218,7 @@ fn format_json_error(error: serde_json::Error) -> EcoString {
 /// The TOML file in the example consists of a table with the keys `title`,
 /// `version`, and `authors`.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #let details = toml("details.toml")
 ///
@@ -302,7 +302,7 @@ fn format_toml_error(error: toml::de::Error) -> EcoString {
 /// each with a sequence of their own submapping with the keys
 /// "title" and "published"
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #let bookshelf(contents) = {
 ///   for (author, works) in contents {
@@ -384,7 +384,7 @@ fn format_yaml_error(error: serde_yaml::Error) -> EcoString {
 /// `content` tag contains one or more paragraphs, which are represented as `p`
 /// tags.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #let findChild(elem, tag) = {
 ///   elem.children

library/src/compute/foundations.rs

@@ -4,7 +4,7 @@ use crate::prelude::*;
 ///
 /// Returns the name of the value's type.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #type(12) \
 /// #type(14.7) \
@@ -34,7 +34,7 @@ pub fn type_(
 /// **Note:** This function is for debugging purposes. Its output should not be
 /// considered stable and may change at any time!
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #none vs #repr(none) \
 /// #"hello" vs #repr("hello") \
@@ -55,7 +55,7 @@ pub fn repr(
 
 /// Fail with an error.
 ///
-/// ## Example
+/// ## Example { #example }
 /// The code below produces the error `panicked with: "this is wrong"`.
 /// ```typ
 /// #panic("this is wrong")
@@ -91,7 +91,7 @@ pub fn panic(
 /// If you wish to test equality between two values, see
 /// [`assert.eq`]($func/assert.eq) and [`assert.ne`]($func/assert.ne).
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```typ
 /// #assert(1 < 2, message: "math broke")
 /// ```
@@ -128,8 +128,8 @@ pub fn assert(
 /// Fails with an error if the first value is not equal to the second. Does not
 /// produce any output in the document.
 ///
-/// ## Example
+/// ## Example { #example }
-/// ```example
+/// ```typ
 /// #assert.eq(10, 10)
 /// ```
 ///
@@ -170,8 +170,8 @@ pub fn assert_eq(
 /// Fails with an error if the first value is equal to the second. Does not
 /// produce any output in the document.
 ///
-/// ## Example
+/// ## Example { #example }
-/// ```example
+/// ```typ
 /// #assert.ne(3, 4)
 /// ```
 ///
@@ -211,7 +211,7 @@ pub fn assert_ne(
 ///
 /// This function should only be used as a last resort.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #eval("1 + 1") \
 /// #eval("(1, 2, 3, 4)").len() \

library/src/layout/align.rs

@@ -2,7 +2,7 @@ use crate::prelude::*;
 
 /// Align content horizontally and vertically.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set align(center)
 ///

library/src/layout/columns.rs

@@ -9,7 +9,7 @@ use crate::text::TextElem;
 /// height on the page. The columns function can break across pages if
 /// necessary.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// = Towards Advanced Deep Learning
 ///
@@ -132,7 +132,7 @@ impl Layout for ColumnsElem {
 /// single column layout or the last column on a page. Otherwise, content after
 /// the column break will be placed in the next column.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set page(columns: 2)
 /// Preliminary findings from our

library/src/layout/container.rs

@@ -9,7 +9,7 @@ use crate::prelude::*;
 /// elements into a paragraph. Boxes take the size of their contents by default
 /// but can also be sized explicitly.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// Refer to the docs
 /// #box(
@@ -170,7 +170,7 @@ impl Layout for BoxElem {
 /// Such a container can be used to separate content, size it and give it a
 /// background or border.
 ///
-/// ## Examples
+/// ## Examples { #examples }
 /// With a block, you can give a background to content while still allowing it
 /// to break across multiple pages.
 /// ```example

library/src/layout/enum.rs

@@ -11,7 +11,7 @@ use super::GridLayouter;
 ///
 /// Displays a sequence of items vertically and numbers them consecutively.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// Automatically numbered:
 /// + Preparations
@@ -47,7 +47,7 @@ use super::GridLayouter;
 /// )
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This functions also has dedicated syntax:
 ///
 /// - Starting a line with a plus sign creates an automatically numbered

library/src/layout/grid.rs

@@ -34,7 +34,7 @@ use super::Sizing;
 /// instead of an array. For example, `columns:` `{3}` is equivalent to
 /// `columns:` `{(auto, auto, auto)}`.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set text(10pt, style: "italic")
 /// #let cell = rect.with(

library/src/layout/hide.rs

@@ -7,7 +7,7 @@ use crate::prelude::*;
 /// content. It may also be useful to redact content because its arguments are
 /// not included in the output.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// Hello Jane \
 /// #hide[Hello] Joe

library/src/layout/list.rs

@@ -9,7 +9,7 @@ use super::GridLayouter;
 /// Displays a sequence of items vertically, with each item introduced by a
 /// marker.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// - *Content*
 ///   - Text
@@ -28,7 +28,7 @@ use super::GridLayouter;
 ///   )
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This functions also has dedicated syntax: Start a line with a hyphen,
 /// followed by a space to create a list item. A list item can contain multiple
 /// paragraphs and other block-level content. All content that is indented

library/src/layout/measure.rs

@@ -8,6 +8,7 @@ use crate::prelude::*;
 /// If you want to measure in the current layout dimensions, you can combined
 /// `measure` and [`layout`]($func/layout).
 ///
+/// # Example { #example }
 /// The same content can have a different size depending on the styles that
 /// are active when it is layouted. For example, in the example below
 /// `[#content]` is of course bigger when we increase the font size.

library/src/layout/pad.rs

@@ -6,7 +6,7 @@ use crate::prelude::*;
 /// for each side individually, or for all sides at once by specifying a
 /// positional argument.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set align(center)
 ///

library/src/layout/page.rs

@@ -14,7 +14,7 @@ use crate::prelude::*;
 /// Pages can be set to use `{auto}` as their width or height. In this case,
 /// the pages will grow to fit their content on the respective axis.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// >>> #set page(margin: auto)
 /// #set page("us-letter")
@@ -415,7 +415,7 @@ impl PageElem {
 ///
 /// Must not be used inside any containers.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// The next page contains
 /// more details on compound theory.

library/src/layout/par.rs

@@ -18,7 +18,7 @@ use crate::text::{
 /// properties, it can also be used to explicitly render its argument onto a
 /// paragraph of its own.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set par(first-line-indent: 1em, justify: true)
 /// #show par: set block(spacing: 0.65em)
@@ -203,7 +203,7 @@ pub enum Linebreaks {
 /// [for loops]($scripting/#loops). Multiple consecutive
 /// paragraph breaks collapse into a single one.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #for i in range(3) {
 ///   [Blind text #i: ]
@@ -212,7 +212,7 @@ pub enum Linebreaks {
 /// }
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// Instead of calling this function, you can insert a blank line into your
 /// markup to create a paragraph break.
 ///

library/src/layout/place.rs

@@ -7,7 +7,7 @@ use crate::prelude::*;
 /// other content in the container. Page margins will be respected.
 ///
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set page(height: 60pt)
 /// Hello, world!

library/src/layout/repeat.rs

@@ -12,7 +12,7 @@ use super::AlignElem;
 /// Errors if there no bounds on the available space, as it would create
 /// infinite content.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// Sign on the dotted line:
 /// #box(width: 1fr, repeat[.])

library/src/layout/spacing.rs

@@ -8,14 +8,14 @@ use crate::prelude::*;
 /// remaining space on the line is distributed among all fractional spacings
 /// according to their relative fractions.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// First #h(1cm) Second \
 /// First #h(30%) Second \
 /// First #h(2fr) Second #h(1fr) Third
 /// ```
 ///
-/// ## Mathematical Spacing
+/// ## Mathematical Spacing { #math-spacing }
 /// In [mathematical formulas]($category/math), you can additionally use these
 /// constants to add spacing between elements: `thin`, `med`, `thick`, `quad`.
 ///
@@ -68,7 +68,7 @@ impl Behave for HElem {
 /// the remaining space on the page is distributed among all fractional spacings
 /// according to their relative fractions.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #grid(
 ///   rows: 3cm,

library/src/layout/stack.rs

@@ -6,7 +6,7 @@ use crate::prelude::*;
 /// The stack places a list of items along an axis, with optional spacing
 /// between each item.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #stack(
 ///   dir: ttb,

library/src/layout/table.rs

@@ -13,7 +13,7 @@ use crate::prelude::*;
 /// To give a table a caption and make it [referenceable]($func/ref), put it
 /// into a [figure]($func/figure).
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #table(
 ///   columns: (1fr, auto, auto),

library/src/layout/terms.rs

@@ -8,14 +8,14 @@ use crate::prelude::*;
 /// descriptions span over multiple lines, they use hanging indent to
 /// communicate the visual hierarchy.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// / Ligature: A merged glyph.
 /// / Kerning: A spacing adjustment
 ///   between two adjacent letters.
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: Starting a line with a slash,
 /// followed by a term, a colon and a description creates a term list item.
 ///

library/src/layout/transform.rs

@@ -8,7 +8,7 @@ use crate::prelude::*;
 /// it at the original positions. Containers will still be sized as if the content
 /// was not moved.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #rect(inset: 0pt, move(
 ///   dx: 6pt, dy: 6pt,
@@ -58,7 +58,7 @@ impl Layout for MoveElem {
 /// Rotate an element by a given angle. The layout will act as if the element
 /// was not rotated.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #stack(
 ///   dir: ltr,
@@ -131,7 +131,7 @@ impl Layout for RotateElem {
 /// affecting the layout.
 ///
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set align(center)
 /// #scale(x: -100%)[This is mirrored.]

library/src/math/accent.rs

@@ -5,7 +5,7 @@ const ACCENT_SHORT_FALL: Em = Em::new(0.5);
 
 /// Attach an accent to a base.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $grave(a) = accent(a, `)$ \
 /// $arrow(a) = accent(a, arrow)$ \

library/src/math/attach.rs

@@ -2,7 +2,7 @@ use super::*;
 
 /// A base with optional attachments.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// // With syntax.
 /// $ sum_(i=0)^n a_i = 2^(1+i) $
@@ -14,7 +14,7 @@ use super::*;
 /// ) $
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax for attachments after the base: Use
 /// the underscore (`_`) to indicate a subscript i.e. bottom attachment and the
 /// hat (`^`) to indicate a superscript i.e. top attachment.
@@ -99,7 +99,7 @@ impl LayoutMath for AttachElem {
 
 /// Force a base to display attachments as scripts.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ scripts(sum)_1^2 != sum_1^2 $
 /// ```
@@ -122,7 +122,7 @@ impl LayoutMath for ScriptsElem {
 
 /// Force a base to display attachments as limits.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ limits(A)_1^2 != A_1^2 $
 /// ```

library/src/math/cancel.rs

@@ -4,7 +4,7 @@ use super::*;
 ///
 /// This is commonly used to show the eliminiation of a term.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// >>> #set page(width: 140pt)
 /// Here, we can simplify:

library/src/math/delimited.rs

@@ -8,7 +8,7 @@ pub(super) const DELIM_SHORT_FALL: Em = Em::new(0.1);
 /// While matched delimiters scale by default, this can be used to scale
 /// unmatched delimiters and to control the delimiter scaling more precisely.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ lr(]a, b/2]) $
 /// $ lr(]sum_(x=1)^n] x, size: #50%) $
@@ -108,7 +108,7 @@ fn scale(
 
 /// Floor an expression.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ floor(x/2) $
 /// ```
@@ -126,7 +126,7 @@ pub fn floor(
 
 /// Ceil an expression.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ ceil(x/2) $
 /// ```
@@ -144,7 +144,7 @@ pub fn ceil(
 
 /// Round an expression.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ round(x/2) $
 /// ```
@@ -162,7 +162,7 @@ pub fn round(
 
 /// Take the absolute value of an expression.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ abs(x/2) $
 /// ```
@@ -181,7 +181,7 @@ pub fn abs(
 
 /// Take the norm of an expression.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ norm(x/2) $
 /// ```

library/src/math/frac.rs

@@ -4,13 +4,13 @@ const FRAC_AROUND: Em = Em::new(0.1);
 
 /// A mathematical fraction.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ 1/2 < (x+1)/2 $
 /// $ ((x+1)) / 2 = frac(a, b) $
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: Use a slash to turn neighbouring
 /// expressions into a fraction. Multiple atoms can be grouped into a single
 /// expression using round grouping parenthesis. Such parentheses are removed
@@ -38,7 +38,7 @@ impl LayoutMath for FracElem {
 
 /// A binomial expression.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ binom(n, k) $
 /// ```

library/src/math/matrix.rs

@@ -8,7 +8,7 @@ const VERTICAL_PADDING: Ratio = Ratio::new(0.1);
 ///
 /// Content in the vector's elements can be aligned with the `&` symbol.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ vec(a, b, c) dot vec(1, 2, 3)
 ///     = a + 2b + 3c $
@@ -57,7 +57,7 @@ impl LayoutMath for VecElem {
 ///
 /// Content in cells that are in the same row can be aligned with the `&` symbol.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ mat(
 ///   1, 2, ..., 10;
@@ -134,7 +134,7 @@ impl LayoutMath for MatElem {
 ///
 /// Content across different branches can be aligned with the `&` symbol.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ f(x, y) := cases(
 ///   1 "if" (x dot y)/2 <= 0,

library/src/math/mod.rs

@@ -117,7 +117,7 @@ pub fn module() -> Module {
 ///
 /// Can be displayed inline with text or as a separate block.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set text(font: "New Computer Modern")
 ///
@@ -130,7 +130,7 @@ pub fn module() -> Module {
 /// $ sum_(k=1)^n k = (n(n+1)) / 2 $
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: Write mathematical markup within
 /// dollar signs to create an equation. Starting and ending the equation with at
 /// least one space lifts it into a separate block that is centered

library/src/math/op.rs

@@ -4,14 +4,14 @@ use super::*;
 
 /// A text operator in an equation.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ tan x = (sin x)/(cos x) $
 /// $ op("custom",
 ///      limits: #true)_(n->oo) n $
 /// ```
 ///
-/// ## Predefined Operators
+/// ## Predefined Operators { #predefined }
 /// Typst predefines the operators `arccos`,  `arcsin`,  `arctan`,  `arg`,
 /// `cos`,  `cosh`,  `cot`, `ctg`, `coth`,  `csc`,  `deg`,  `det`,  `dim`,
 /// `exp`, `gcd`,  `hom`,  `mod`,  `inf`,  `ker`,  `lg`,  `lim`,  `ln`,  `log`,

library/src/math/root.rs

@@ -2,7 +2,7 @@ use super::*;
 
 /// A square root.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ sqrt(x^2) = x = sqrt(x)^2 $
 /// ```
@@ -20,7 +20,7 @@ pub fn sqrt(
 
 /// A general root.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ root(3, x) $
 /// ```

library/src/math/style.rs

@@ -2,7 +2,7 @@ use super::*;
 
 /// Bold font style in math.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ bold(A) := B^+ $
 /// ```
@@ -20,7 +20,7 @@ pub fn bold(
 
 /// Upright (non-italic) font style in math.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ upright(A) != A $
 /// ```
@@ -70,7 +70,7 @@ pub fn serif(
 
 /// Sans-serif font style in math.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ sans(A B C) $
 /// ```
@@ -91,7 +91,7 @@ pub fn sans(
 
 /// Calligraphic font style in math.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// Let $cal(P)$ be the set of ...
 /// ```
@@ -112,7 +112,7 @@ pub fn cal(
 
 /// Fraktur font style in math.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ frak(P) $
 /// ```
@@ -133,7 +133,7 @@ pub fn frak(
 
 /// Monospace font style in math.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ mono(x + y = z) $
 /// ```
@@ -157,7 +157,7 @@ pub fn mono(
 /// For uppercase latin letters, blackboard bold is additionally available
 /// through [symbols]($category/symbols/sym) of the form `NN` and `RR`.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ bb(b) $
 /// $ bb(N) = NN $

library/src/math/underover.rs

@@ -6,7 +6,7 @@ const BRACKET_GAP: Em = Em::new(0.25);
 
 /// A horizontal line under content.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ underline(1 + 2 + ... + 5) $
 /// ```
@@ -29,7 +29,7 @@ impl LayoutMath for UnderlineElem {
 
 /// A horizontal line over content.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ overline(1 + 2 + ... + 5) $
 /// ```
@@ -52,7 +52,7 @@ impl LayoutMath for OverlineElem {
 
 /// A horizontal brace under content, with an optional annotation below.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ underbrace(1 + 2 + ... + 5, "numbers") $
 /// ```
@@ -87,7 +87,7 @@ impl LayoutMath for UnderbraceElem {
 
 /// A horizontal brace over content, with an optional annotation above.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ overbrace(1 + 2 + ... + 5, "numbers") $
 /// ```
@@ -122,7 +122,7 @@ impl LayoutMath for OverbraceElem {
 
 /// A horizontal bracket under content, with an optional annotation below.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ underbracket(1 + 2 + ... + 5, "numbers") $
 /// ```
@@ -157,7 +157,7 @@ impl LayoutMath for UnderbracketElem {
 
 /// A horizontal bracket over content, with an optional annotation above.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// $ overbracket(1 + 2 + ... + 5, "numbers") $
 /// ```

library/src/meta/counter.rs

@@ -16,7 +16,7 @@ use crate::prelude::*;
 /// headings, figures, and more. Moreover, you can define custom counters for
 /// other things you want to count.
 ///
-/// ## Displaying a counter
+/// ## Displaying a counter { #displaying }
 /// To display the current value of the heading counter, you call the `counter`
 /// function with the `key` set to `heading` and then call the `display` method
 /// on the counter. To see any output, you also have to enable heading
@@ -40,7 +40,7 @@ use crate::prelude::*;
 /// #counter(heading).display("I")
 /// ```
 ///
-/// ## Modifying a counter
+/// ## Modifying a counter { #modifying }
 /// To modify a counter, you can use the `step` and `update` methods:
 ///
 /// - The `step` method increases the value of the counter by one. Because
@@ -75,7 +75,7 @@ use crate::prelude::*;
 /// Still at #counter(heading).display().
 /// ```
 ///
-/// ## Custom counters
+/// ## Custom counters { #custom-counters }
 /// To define your own counter, call the `counter` function with a string as a
 /// key. This key identifies the counter globally.
 ///
@@ -88,7 +88,7 @@ use crate::prelude::*;
 /// #mine.display() \
 /// ```
 ///
-/// ## How to step
+/// ## How to step { #how-to-step }
 /// When you define and use a custom counter, in general, you should first step
 /// the counter and then display it. This way, the stepping behaviour of a
 /// counter can depend on the element it is stepped for. If you were writing a
@@ -117,7 +117,7 @@ use crate::prelude::*;
 /// they always start at zero. This way, they are at one for the first display
 /// (which happens after the first step).
 ///
-/// ## Page counter
+/// ## Page counter { #page-counter }
 /// The page counter is special. It is automatically stepped at each pagebreak.
 /// But like other counters, you can also step it manually. For example, you
 /// could have Roman page numbers for your preface, then switch to Arabic page
@@ -144,7 +144,7 @@ use crate::prelude::*;
 /// Arabic numbers.
 /// ```
 ///
-/// ## Time travel
+/// ## Time travel { #time-travel }
 /// Counters can travel through time! You can find out the final value of the
 /// counter before it is reached and even determine what the value was at any
 /// particular location in the document.
@@ -195,7 +195,7 @@ use crate::prelude::*;
 ///   which one doesn't matter. After the heading follow two calls to `step()`,
 ///   so the final value is `{(6,)}`.
 ///
-/// ## Other kinds of state
+/// ## Other kinds of state { #other-state }
 /// The `counter` function is closely related to [state]($func/state) function.
 /// Read its documentation for more details on state management in Typst and
 /// why it doesn't just use normal variables for counters.

library/src/meta/figure.rs

@@ -15,7 +15,7 @@ use crate::visualize::ImageElem;
 /// For example, figures containing images will be numbered separately from
 /// figures containing tables.
 ///
-/// ## Examples
+/// ## Examples { #examples }
 /// The example below shows a basic figure with an image:
 /// ```example
 /// @glacier shows a glacier. Glaciers
@@ -45,7 +45,7 @@ use crate::visualize::ImageElem;
 /// This behaviour can be overridden by explicitly specifying the figure's
 /// `kind`. All figures of the same kind share a common counter.
 ///
-/// ## Modifying the appearance
+/// ## Modifying the appearance { #modifying-appearance }
 /// You can completely customize the look of your figures with a [show
 /// rule]($styling/#show-rules). In the example below, we show the figure's
 /// caption above its body and display its supplement and counter after the

library/src/meta/heading.rs

@@ -24,7 +24,7 @@ use crate::text::{SpaceElem, TextElem, TextSize};
 /// headings from this outline, you can set the `outlined` parameter to
 /// `{false}`.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set heading(numbering: "1.a)")
 ///
@@ -35,7 +35,7 @@ use crate::text::{SpaceElem, TextElem, TextSize};
 /// To start, ...
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// Headings have dedicated syntax: They can be created by starting a line with
 /// one or multiple equals signs, followed by a space. The number of equals
 /// signs determines the heading's logical nesting depth.

library/src/meta/link.rs

@@ -8,7 +8,7 @@ use crate::text::{Hyphenate, TextElem};
 /// are not styled any different from normal text. However, you can easily apply
 /// a style of your choice with a show rule.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #show link: underline
 ///
@@ -20,7 +20,7 @@ use crate::text::{Hyphenate, TextElem};
 /// ]
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: Text that starts with `http://` or
 /// `https://` is automatically turned into a link.
 ///

library/src/meta/numbering.rs

@@ -16,7 +16,7 @@ use crate::text::Case;
 /// number is substituted, their prefixes, and one suffix. The prefixes and the
 /// suffix are repeated as-is.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #numbering("1.1)", 1, 2, 3) \
 /// #numbering("1.a.i", 1, 2) \

library/src/meta/outline.rs

@@ -16,7 +16,7 @@ use crate::text::{LinebreakElem, SpaceElem, TextElem};
 /// be displayed in the outline alongside its title or caption. By default this
 /// generates a table of contents.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #outline()
 ///
@@ -27,7 +27,7 @@ use crate::text::{LinebreakElem, SpaceElem, TextElem};
 /// #lorem(10)
 /// ```
 ///
-/// ## Alternative outlines
+/// ## Alternative outlines { #alternative-outlines }
 /// By setting the `target` parameter, the outline can be used to generate a
 /// list of other kinds of elements than headings. In the example below, we list
 /// all figures containing images by setting `target` to `{figure.where(kind:

library/src/meta/query.rs

@@ -10,7 +10,7 @@ use crate::prelude::*;
 /// find all elements, just the ones before that location, or just the ones
 /// after it.
 ///
-/// ## Finding elements
+/// ## Finding elements { #finding-elements }
 /// In the example below, we create a custom page header that displays the text
 /// "Typst Academy" in small capitals and the current section title. On the
 /// first page, the section title is omitted because the header is before the
@@ -62,7 +62,7 @@ use crate::prelude::*;
 /// #lorem(15)
 /// ```
 ///
-/// ## A word of caution
+/// ## A word of caution { #caution }
 /// To resolve all your queries, Typst evaluates and layouts parts of the
 /// document multiple times. However, there is no guarantee that your queries
 /// can actually be completely resolved. If you aren't careful a query can
@@ -89,7 +89,7 @@ use crate::prelude::*;
 /// })
 /// ```
 ///
-/// ## Migration Hints
+/// ## Migration Hints { #migration-hints }
 /// The `before` and `after` arguments have been removed in version 0.3.0. You
 /// can now use flexible selector combinator methods instead. For example,
 /// `query(heading, before: loc)` becomes `query(heading.before(loc), loc)`.

library/src/meta/reference.rs

@@ -19,7 +19,7 @@ use crate::text::TextElem;
 /// If you just want to link to a labelled element and not get an automatic
 /// textual reference, consider using the [`link`]($func/link) function instead.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set heading(numbering: "1.")
 /// #set math.equation(numbering: "(1)")
@@ -43,7 +43,7 @@ use crate::text::TextElem;
 /// #bibliography("works.bib")
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: A reference to a label can be
 /// created by typing an `@` followed by the name of the label (e.g.
 /// `[= Introduction <intro>]` can be referenced by typing `[@intro]`).
@@ -51,7 +51,7 @@ use crate::text::TextElem;
 /// To customize the supplement, add content in square brackets after the
 /// reference: `[@intro[Chapter]]`.
 ///
-/// ## Customization
+/// ## Customization { #customization }
 /// If you write a show rule for references, you can access the referenced
 /// element through the `element` field of the reference. The `element` may
 /// be `{none}` even if it exists if Typst hasn't discovered it yet, so you

library/src/meta/state.rs

@@ -29,7 +29,7 @@ use crate::prelude::*;
 /// #compute("x - 5")
 /// ```
 ///
-/// ## State and document markup
+/// ## State and document markup { #state-and-markup }
 /// Why does it do that? Because, in general, this kind of computation with side
 /// effects is problematic in document markup and Typst is upfront about that.
 /// For the results to make sense, the computation must proceed in the same
@@ -60,7 +60,7 @@ use crate::prelude::*;
 /// `template` function and only then sees the `Outline`. Just counting up would
 /// number the `Introduction` with `1` and the `Outline` with `2`.
 ///
-/// ## Managing state in Typst
+/// ## Managing state in Typst { #state-in-typst }
 /// So what do we do instead? We use Typst's state management system. Calling
 /// the `state` function with an identifying string key and an optional initial
 /// value gives you a state value which exposes a few methods. The two most
@@ -123,7 +123,7 @@ use crate::prelude::*;
 /// what you want! A good example are heading counters, which is why Typst's
 /// [counting system]($func/counter) is very similar to its state system.
 ///
-/// ## Time Travel
+/// ## Time Travel { #time-travel }
 /// By using Typst's state management system you also get time travel
 /// capabilities! By combining the state system with [`locate`]($func/locate)
 /// and [`query`]($func/query), we can find out what the value of the state will
@@ -155,7 +155,7 @@ use crate::prelude::*;
 /// #compute("x - 5")
 /// ```
 ///
-/// ## A word of caution
+/// ## A word of caution { #caution }
 /// To resolve the values of all states, Typst evaluates parts of your code
 /// multiple times. However, there is no guarantee that your state manipulation
 /// can actually be completely resolved.

library/src/text/deco.rs

@@ -6,7 +6,7 @@ use crate::prelude::*;
 
 /// Underline text.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// This is #underline[important].
 /// ```
@@ -80,7 +80,7 @@ impl Show for UnderlineElem {
 
 /// Add a line over text.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #overline[A line over text.]
 /// ```
@@ -160,7 +160,7 @@ impl Show for OverlineElem {
 
 /// Strike through text.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// This is #strike[not] relevant.
 /// ```

library/src/text/misc.rs

@@ -28,14 +28,14 @@ impl PlainText for SpaceElem {
 /// end of a paragraph is ignored, but more than one creates additional empty
 /// lines.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// *Date:* 26.12.2022 \
 /// *Topic:* Infrastructure Test \
 /// *Severity:* High \
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: To insert a line break, simply write
 /// a backslash followed by whitespace. This always creates an unjustified
 /// break.
@@ -71,7 +71,7 @@ impl Behave for LinebreakElem {
 ///
 /// Increases the current font weight by a given `delta`.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// This is *strong.* \
 /// This is #strong[too.] \
@@ -80,7 +80,7 @@ impl Behave for LinebreakElem {
 /// And this is *evermore.*
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: To strongly emphasize content,
 /// simply enclose it in stars/asterisks (`*`). Note that this only works at
 /// word boundaries. To strongly emphasize part of a word, you have to use the
@@ -139,7 +139,7 @@ impl Fold for Delta {
 /// - If it is already `{"italic"}` or `{"oblique"}`,
 ///   it turns it back to `{"normal"}`.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// This is _emphasized._ \
 /// This is #emph[too.]
@@ -151,7 +151,7 @@ impl Fold for Delta {
 /// This is _emphasized_ differently.
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: To emphasize content, simply
 /// enclose it in underscores (`_`). Note that this only works at word
 /// boundaries. To emphasize part of a word, you have to use the function.
@@ -195,7 +195,7 @@ impl Fold for Toggle {
 
 /// Convert text or content to lowercase.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #lower("ABC") \
 /// #lower[*My Text*] \
@@ -215,7 +215,7 @@ pub fn lower(
 
 /// Convert text or content to uppercase.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #upper("abc") \
 /// #upper[*my text*] \
@@ -280,7 +280,7 @@ impl Case {
 /// support selecting a dedicated smallcaps font as well as synthesizing
 /// smallcaps from normal letters, but this is not yet implemented.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set par(justify: true)
 /// #set heading(numbering: "I.")
@@ -313,7 +313,7 @@ pub fn smallcaps(
 /// the same but randomly chosen. As usual for blind texts, it does not make any
 /// sense. Use it as a placeholder to try layouts.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// = Blind Text
 /// #lorem(30)

library/src/text/mod.rs

@@ -47,7 +47,7 @@ pub(super) fn define(global: &mut Scope) {
 /// rule is often the simpler choice, calling the text function directly can be
 /// useful when passing text as an argument to another function.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set text(18pt)
 /// With a set rule.

library/src/text/quotes.rs

@@ -7,7 +7,7 @@ use crate::prelude::*;
 /// Automatically turns into an appropriate opening or closing quote based on
 /// the active [text language]($func/text.lang).
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// "This is in quotes."
 ///
@@ -18,7 +18,7 @@ use crate::prelude::*;
 /// "C'est entre guillemets."
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: The normal quote characters
 /// (`'` and `"`). Typst automatically makes your quotes smart.
 ///

library/src/text/raw.rs

@@ -14,7 +14,7 @@ use crate::prelude::*;
 /// Displays the text verbatim and in a monospace font. This is typically used
 /// to embed computer code into your document.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ````example
 /// Adding `rbx` to `rcx` gives
 /// the desired result.
@@ -26,7 +26,7 @@ use crate::prelude::*;
 /// ```
 /// ````
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax. You can enclose text in 1 or 3+
 /// backticks (`` ` ``) to make it raw. Two backticks produce empty raw text.
 /// When you use three or more backticks, you can additionally specify a

library/src/text/shift.rs

@@ -5,7 +5,7 @@ use crate::prelude::*;
 ///
 /// The text is rendered smaller and its baseline is lowered.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// Revenue#sub[yearly]
 /// ```
@@ -68,7 +68,7 @@ impl Show for SubElem {
 ///
 /// The text is rendered smaller and its baseline is raised.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// 1#super[st] try!
 /// ```

library/src/visualize/image.rs

@@ -11,7 +11,7 @@ use crate::text::families;
 ///
 /// Supported formats are PNG, JPEG, GIF and SVG.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #figure(
 ///   image("molecular.jpg", width: 80%),

library/src/visualize/line.rs

@@ -2,7 +2,7 @@ use crate::prelude::*;
 
 /// A line from one point to another.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set page(height: 100pt)
 ///

library/src/visualize/path.rs

@@ -4,7 +4,7 @@ use kurbo::{CubicBez, ParamCurveExtrema};
 
 /// A path through a list of points, connected by Bezier curves.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #path(
 ///   fill: blue.lighten(80%),

library/src/visualize/polygon.rs

@@ -4,7 +4,7 @@ use crate::prelude::*;
 ///
 /// The polygon is defined by its corner points and is closed automatically.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #polygon(
 ///   fill: blue.lighten(80%),

library/src/visualize/shape.rs

@@ -4,7 +4,7 @@ use crate::prelude::*;
 
 /// A rectangle with optional content.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// // Without content.
 /// #rect(width: 35%, height: 30pt)
@@ -180,7 +180,7 @@ impl Layout for RectElem {
 
 /// A square with optional content.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// // Without content.
 /// #square(size: 40pt)
@@ -291,7 +291,7 @@ impl Layout for SquareElem {
 
 /// An ellipse with optional content.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// // Without content.
 /// #ellipse(width: 35%, height: 30pt)
@@ -374,7 +374,7 @@ impl Layout for EllipseElem {
 
 /// A circle with optional content.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// // Without content.
 /// #circle(radius: 25pt)